Skip to main content
When something isn’t working as expected in Stairoids, the Signal Activity Log is your first stop. Navigate to Settings → Logs to see a real-time stream of every inbound signal, outbound automation execution, and webhook delivery in your workspace — including their status (success, failed, retrying) and any associated error messages. Most issues can be diagnosed in under a minute by filtering the log by the relevant signal ID, account domain, or time window.
Every API response body — including error responses — includes a request_id field. Make a note of this value whenever you encounter an unexpected result. Stairoids support can use it to look up the exact request when investigating your issue. Always include it in your support ticket.

​
Signals Not Arriving

If signals from a connected source are not appearing in Stairoids, work through the following checks in order.
Navigate to Settings → Integrations and locate the relevant integration (e.g., Segment, HubSpot, or your custom API source). Confirm that its status toggle shows Enabled (green). If it’s disabled, click the toggle to re-enable it — new signals begin flowing immediately.Also confirm that the integration is configured to send the event types you’re expecting. Some integrations have event-type filters that can silently drop certain signal categories.
If you’re ingesting signals via the REST API, your API key must be a Read-Write key. A Read-only key returns a 403 Forbidden error when you attempt to create a signal, and the signal will not be recorded.To verify: go to Settings → API Keys and confirm the key you’re using shows Read-Write in the Scope column. If it shows Read-only, generate a new Read-Write key and update your integration. See Rotating Keys for a zero-downtime procedure.
For incoming webhook integrations, check that the source tool is configured with the exact webhook URL shown in Settings → Automations → Incoming. A missing trailing slash, a typo in the path, or an outdated URL from a previous setup can silently drop all incoming traffic.Use your source tool’s delivery log (most platforms like Zapier, Segment, and HubSpot show per-event delivery status) to confirm the request is being sent and what HTTP status code the endpoint is returning.
Open Settings → Logs and filter by the time window when you expected signals to arrive. Look for entries with a failed status and expand them to see the full error message. Common errors include:
  • invalid_payload: The signal body is missing a required field. The error message will specify which field. The most common culprits are a missing type, account.domain, or contact.email.
  • domain_excluded: The domain in the signal matches an entry in your Excluded Domains list under Settings → Account Matching. Remove the domain from the exclusion list if this is unintended.
  • rate_limit_exceeded: Your API key has hit its per-minute request limit. Implement backoff and retry logic in your integration.

​
Outgoing Automation Not Firing

If a configured automation isn’t triggering when you expect it to, step through these checks before raising a support ticket.
Open the automation editor and click Simulate in the top toolbar. Paste a sample signal JSON payload and run the simulation — Stairoids evaluates the automation’s trigger conditions against your sample and shows you exactly which conditions passed, which failed, and why.Common trigger condition mistakes include using the wrong signal type name (e.g., pageview instead of page_view), referencing a property key with the wrong casing, or setting a score threshold higher than any account in your workspace currently achieves.
Navigate to Settings → Integrations and click on the destination integration the automation writes to (e.g., Slack, HubSpot CRM, Salesforce). Verify its connection status shows Connected. If it shows Reconnection Required, the OAuth token or API credentials have expired — click Reconnect and re-authorize the integration.OAuth tokens for many CRMs and communication tools expire after 60–90 days of inactivity. Reconnecting takes under a minute and does not affect historical data.
In the Automations list (Automations → Outgoing), check that the automation’s status toggle is green (enabled). A disabled automation does not evaluate triggers or execute actions — it silently skips all matching signals. Click the toggle to re-enable it.Also confirm the automation hasn’t been accidentally paused. A paused automation shows a yellow Paused badge and can be resumed from the automation detail page.
Go to Settings → Logs and filter by the automation name or ID. If the automation triggered but the destination action failed, you’ll see a failed entry with a detailed error from the downstream API (e.g., a missing required CRM field, an invalid Slack channel ID, or a payload validation error). Fix the underlying issue and use the Retry button to re-run the failed execution against the same signal.

​
API Errors

A 401 response means the Authorization header is missing, the key value is malformed, or the key has been revoked.Steps to resolve:
  1. Confirm your request includes the header: Authorization: Bearer <your-api-key>
  2. Go to Settings → API Keys and verify the key appears in the list and is not marked as revoked.
  3. If the key is missing or revoked, generate a new one, update your integration, and test again.
  4. Check that you haven’t accidentally included extra whitespace, newlines, or quotes around the key value when reading it from an environment variable.
A 422 response means the API received your request but the payload failed validation. The response body contains a details array that lists every validation error and the specific field that caused it.
{
  "error": "unprocessable_entity",
  "message": "Request payload failed validation.",
  "details": [
    { "field": "type", "message": "type is required" },
    { "field": "account.domain", "message": "account.domain must be a valid domain name" }
  ],
  "request_id": "req_01HXYZ9999AABBCC"
}
The most common causes are:
  • Missing type field on a signal creation request.
  • Missing both account.domain and contact.email — at least one is required to attribute a signal to an account or contact.
  • Providing an account.domain value that includes a protocol prefix (e.g., https://acme.com instead of acme.com).
  • Sending a created_at timestamp in a format other than ISO 8601 UTC.
A 429 response means your API key has exceeded its allowed request rate. The response includes two headers to help you back off correctly:
  • Retry-After: The number of seconds to wait before making another request.
  • X-RateLimit-Reset: The Unix timestamp at which your rate limit window resets.
HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718462400
Implement exponential backoff with jitter in your integration to handle 429 responses gracefully. If you’re consistently hitting rate limits at your current plan’s ceiling, consider upgrading your plan or batching signal submissions to reduce request volume. See the FAQ — Rate Limits for per-plan limits.
A 500 response indicates an unexpected error on the Stairoids side. These are rare and typically transient. Wait 30 seconds and retry the request. If the error persists for more than a few minutes, check the Stairoids Status Page for any ongoing incidents.When contacting support about a 500 error, include the request_id from the response body — this is the fastest way for the support team to locate and investigate the failed request.

​
Signal Score Not Changing

Engagement score calculations run asynchronously after signal ingestion. When you send a signal via the API, the signal is recorded immediately (you receive a 201 Created response), but the account or contact score is updated in a background job that typically completes within 30–60 seconds.If you query an account’s score immediately after ingesting a signal, you may see the old value. Wait a minute and query again. If the score still hasn’t changed after 60 seconds, proceed to the next check.
Each signal type must have a scoring weight greater than zero to contribute to engagement scores. Navigate to Settings → Scoring and find the signal type you’re testing. If the weight is set to 0, the signal is ingested and stored but adds nothing to the score.Update the weight to a non-zero value and click Save. New signals of that type will contribute to scores immediately. Previously ingested signals of the same type will have their contribution recalculated on the next scoring cycle (typically within a few minutes).
A signal that was attributed to the wrong account — or not attributed to any account at all — won’t affect the score you’re looking at. Open Settings → Logs, find the signal in question, and expand it to see the account.id and account.domain fields that Stairoids resolved.If the signal was attributed to a different account (e.g., due to domain normalization creating a different match), review your domain normalization rules under Settings → Account Matching.
If an account has a very large historical score with strong time decay applied, new low-weight signals may not produce a visibly noticeable change in the displayed score. Navigate to the account’s detail page and open the Score History tab to see a timeline of score changes. You can verify whether the new signal appeared as a positive delta that was offset by decay on the same cycle.Adjust signal weights under Settings → Scoring or tune the decay half-life if scores are decaying faster than your sales cycle warrants.

​
Contacting Support

If you’ve worked through the relevant sections above and the issue persists, reach out to the Stairoids support team:
  • Email: support@stairoids.com
  • In-app chat: Click the ? icon in the bottom-right corner of the dashboard
  • Enterprise Slack: Available for Enterprise plan customers via your dedicated channel
To help the team resolve your issue as quickly as possible, include the following in your message:
  • Workspace ID — found in Settings → General
  • Signal ID or Automation ID — visible in the Activity Log
  • request_id from any relevant API response body
  • The exact error message you’re seeing
  • What you expected to happen and what actually happened
  • Timestamps of the affected events (in UTC)
Every API response — including error responses — contains a request_id field in the JSON body. This single value allows the Stairoids support team to locate the exact request when investigating your issue. It’s the most valuable piece of information you can include in a support request.