Errors

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

{
  "unique_id": "6941049359794271324",
  "http_status_code": 403,
  "code": "missing_access_token",
  "message": "No access_token was provided with this request.",
  "parameters": {}
}

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:

{
  "unique_id": "6941047907334948670",
  "http_status_code": 400,
  "code": "validation_error",
  "message": "Validation failed",
  "parameters": {
    "description": "must not be null"
  }
}

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:

curl -i https://acme.extole.io/events \
  -H "Content-Type: application/json" \
  -d '{"event_name":"purchase","data":{"email":"[email protected]"}}'

HTTP/1.1 200 OK
X-Extole-Token: DI3ZCZ97V3V1F9SUA9T
X-Extole-Error-Message: invalid_email

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 limits:

• 100 requests per minute per IP address or token.
• 10 requests per second per identified person.

The /v6/async-events endpoint is not rate-limited and is the recommended path for high-volume event ingestion.

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.
• 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 [email protected].

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.

curl https://api.extole.io/v6/async-events \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Extole-Debug: 2" \
  -d '{...}'

Debug responses can be verbose; use level 1 in routine logging and reserve 2 or 3 for active troubleshooting.

Support and Escalation

When contacting [email protected] 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