Success bodies are not wrapped. For example,
POST /v0/events returns 202 with { "accepted": 3 }.
Error codes
Every response has an
X-Request-ID header. Include it when you contact support.
Responses without a body
Some responses have a status code and no JSON body:
The OAuth endpoints use the OAuth error format:
{ "error": "invalid_client", "error_description": "..." }.
Rate limits (429)
A429 response means a limit is used up for now. The request itself is fine: send it again later, unchanged.
Every
429 has a Retry-After header with a number of seconds. The events limit is per minute and far above normal traffic, so a 429 there usually means a loop or a backfill that sends too fast.
To handle a 429:
- Read
Retry-Afterand wait at least that many seconds. If the header is missing, use exponential backoff (1, 2, 4, 8 seconds) with some random jitter. - Send the same request again, with the same
message_idfor events, so that a retry does not count twice. - Stop after a few tries and keep the events to send later. Do not retry at once in a tight loop: each try counts against the same limit.
- For a backfill, send fewer events per minute, or spread the batches out.
Handle errors well
- Branch on
code, not onmessageor the status alone. - Retry only
429and5xx. Wait for theRetry-Afterseconds on429. Use exponential backoff on5xx. - Keep the same
message_idon a retry. Reports count eachmessage_idonce, so a retry does not count twice. See idempotency. - Do not retry other
4xxcodes without a change. They fail the same way again.