Skip to main content
Most errors return JSON with a stable code and a message:
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)

A 429 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:
  1. Read Retry-After and wait at least that many seconds. If the header is missing, use exponential backoff (1, 2, 4, 8 seconds) with some random jitter.
  2. Send the same request again, with the same message_id for events, so that a retry does not count twice.
  3. 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.
  4. For a backfill, send fewer events per minute, or spread the batches out.

Handle errors well

  1. Branch on code, not on message or the status alone.
  2. Retry only 429 and 5xx. Wait for the Retry-After seconds on 429. Use exponential backoff on 5xx.
  3. Keep the same message_id on a retry. Reports count each message_id once, so a retry does not count twice. See idempotency.
  4. Do not retry other 4xx codes without a change. They fail the same way again.