code field for programmatic handling. This page documents the error shape, the HTTP status codes Extole returns, the most common error codes by category, and guidance for retries, async events, and support escalation.
Quickstart
- Branch on
code. It is a stable string enum suitable forswitchor pattern-match logic. - Display
messageto humans where appropriate. - Log
unique_idand include it in any support ticket. - Inspect
parametersfor sub-error details when present.
Error Response Structure
For example, a validation error often carries
parameters.description with the specific field and condition that failed:
Asynchronous Error Handling
Consumer event endpoints (POST /events, GET /events/{event_name}) always return HTTP 200 to avoid blocking the participant’s session, regardless of whether the event was processed successfully.
To detect processing errors on these endpoints, inspect the response headers:
Rate Limiting
A429 response with code too_many_requests indicates that the caller has sent too many requests in a window. Extole applies two general limits:
- 100 requests per minute per IP address or token.
- 10 requests per second per identified person.
Event Submission Limits
The synchronous event endpoints,POST /v6/events and POST /v6/events/{event_name}, have a lower limit of their own: 30 requests per client per minute. The count starts again at the beginning of each UTC minute, and every integration that sends events under your client shares the same 30. From the 31st request in a minute until that minute ends, these endpoints return 429.
The asynchronous endpoints, POST /v6/async-events and POST /v6/async-events/{event_name}, have no per-request rate limit and are the recommended path for high-volume event ingestion. They take the same request body and return only the event_id. Extole checks the request before it responds, then identifies the person and processes the event after the response, so the response has no person_id and an error during processing is not returned to the caller. Use /v6/events for low-volume calls that need the person_id or a processing error in the response.
Typical causes of rate limiting:
- A misconfigured tag or integration sending duplicate or dummy events.
- A customer data platform (CDP) misconfigured to forward more data than expected.
- Load testing or security scans (expected and unavoidable in those scenarios).
- Use exponential backoff with jitter. A reasonable starting pattern: 1s, 2s, 4s, 8s, capped at 30s.
- Avoid retrying immediately. Even a 100 ms retry can keep the limit tripped.
- For
/v6/events, retry after the next UTC minute starts, or send the event to/v6/async-eventsinstead. - Distinguish retryable from non-retryable errors.
429and500are retryable;400,401,403,415are not (the request is the problem, not the platform).
Retry Guidance
For state-changing operations (
POST, PATCH, PUT, DELETE), be cautious about retrying after a 5xx. The operation may have succeeded server-side even if the response did not return. Where the API supports idempotency, use it.
Debugging
Set theX-Extole-Debug header to a value between 1 and 3 on any request to receive expanded diagnostic information in the response. Higher levels return more detail.
1 in routine logging and reserve 2 or 3 for active troubleshooting.
Support and Escalation
When contacting support@extole.com about an error:- Include the
unique_idfrom the error response. Extole correlates this with internal logs. - Include the HTTP method, full request path, and a UTC timestamp.
- Include the response body verbatim.
- Do not include the access token in unredacted form.
