Skip to main content
Every error returned by an Extole API follows a consistent JSON structure with a stable 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

When handling errors:
  • Branch on code. It is a stable string enum suitable for switch or pattern-match logic.
  • Display message to humans where appropriate.
  • Log unique_id and include it in any support ticket.
  • Inspect parameters for 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:
For all other endpoints, errors return non-200 status codes with the standard error body.

Rate Limiting

A 429 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).
When implementing retry logic:
  • 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-events instead.
  • Distinguish retryable from non-retryable errors. 429 and 500 are retryable; 400, 401, 403, 415 are not (the request is the problem, not the platform).
If your integration encounters rate limiting that does not match these patterns, contact support@extole.com.

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 the X-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.
Debug responses can be verbose; use level 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_id from 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.
For endpoint-specific behavior or errors not documented here, consult the API reference for the endpoint in question. Each endpoint enumerates the errors it can return.

HTTP Status Codes

Common Errors by Category

Each endpoint’s API reference lists the full set of errors that endpoint can return. The codes below are the most common ones an integrator will encounter, grouped by area.

Authentication and authorization

Validation

Persons

Events

Zones

Rewards

Audiences and memberships

Shareables and shares

Batch jobs and files