This page covers how the REST API reports problems: the error envelope, every status code, the per-event validation errors returned for a batch, the rate limits, and how a well-behaved client should retry.

The error envelope

When a request fails before any events are processed (bad auth, malformed body, a limit breach), the response body is a small, consistent object:

{ "success": false, "error": "Human-readable message" }

Some errors also include an optional, stable, machine-readable code you can switch on instead of matching the human-readable error string. It's additive — clients that read only error / success are unaffected, and not every error carries one:

{ "success": false, "error": "Rate limit exceeded: ...", "code": "rate_limited" }

The per-org 429 backstop and the plan-quota 429s carry no code — match those on status + Retry-After. (See Authentication for the per-key IP / Origin allowlists behind the 403 codes.)

The 413 (payload too large) response carries the same shape plus two machine-readable fields so a client can resize its batch without parsing the prose message:

{
  "success": false,
  "error": "Request body too large: maximum 1048576 bytes",
  "limit_bytes": 1048576,
  "hint": "Split the batch into smaller requests (max 100 events / 1 MiB per call)."
}

This is the /v1-batch 413 (1 MiB cap). /v1-profiles and /v1-consent parse smaller bodies under a shared 256 KiB cap, so their 413 carries limit_bytes: 262144 and a generic hint ("Reduce the request body size…").

HTTP status codes

Request-level error messages

These are returned in the error field for request-level failures:

Response headers

Every response — success or error — carries these headers (they all route through the shared response helper):

CORS preflights allow GET, POST, OPTIONS from any origin (Access-Control-Allow-Origin: *), with Content-Type, Authorization, X-Request-ID request headers.

Versioning

The API is versioned by path prefix (/v1-*) and advertises its major version in the API-Version response header (1 today). A future breaking-change release would ship under a new prefix and bump the header; non-breaking, additive changes (new optional fields, new code values) ship within v1.

Per-event errors

When a batch is accepted but some events fail, the response is 200 with success: false and an errors array. Each entry is "<messageId>: <reason>", and the array lists at most the first ten failures:

{
  "success": false,
  "processed": 1,
  "failed": 1,
  "errors": [ "msg_002: anonymousId is required" ],
  "duration_ms": 31
}

The reasons you may see. Each is a stable, matchable string; raw database errors are never returned to clients (they go to server logs only):

Rate limits

Every endpoint enforces a per-minute request limit, scoped per (organization, client IP). When you exceed it the response is 429 with headers that tell you when to retry:

HTTP/1.1 429 Too Many Requests
Retry-After: 27
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

Retry-After is the seconds until the current minute window resets. The per-IP 429 carries code: "rate_limited".

Per-org backstop. On top of the per-IP limit, /v1-batch also enforces a coarse 2000 requests per minute per organization (aggregated across all IPs), so a leaked write key can't be amplified from many addresses. Exceeding it returns 429 with Retry-After + X-RateLimit-Limit: 2000. Note this per-org 429 body is { "error": "Rate limit exceeded: max 2000 requests per minute per org" } — it does not include success: false or a code field (unlike the per-IP 429), so match it on status.

Two further 429s come from your plan's event quota rather than request rate:

• Monthly event limit reached — Monthly event limit exceeded. Please upgrade your plan. This 429 returns the bare error envelope (no Retry-After); ingestion resumes when the monthly counter resets or you upgrade.
• Ingestion paused — Event quota exceeded. Upgrade your plan to resume ingestion., with Retry-After: 86400 and an upgrade_url. This is a billing/plan state, not a transient throttle — backing off won't clear it; upgrading or the next reset will.

Retry policy

The official Web SDK treats 4xx responses as permanent — it drops the event rather than retrying — and retries 5xx and network errors with exponential backoff plus jitter, up to 3 attempts. This means the SDK treats a 429 as permanent too: it does not read Retry-After or retry rate-limited requests (only the server emits Retry-After). If you need rate-limit retry today, call POST /v1-batch directly — tracked for a future SDK release.

If you build your own client, a safe policy is:

• 2xx — done. Still check failed / errors in the body.
• 400 / 401 / 403 / 413 — permanent. Fix the request (or the key); retrying the same payload will fail the same way.
• 429 — honour the Retry-After header, then retry. For the quota-paused 429 (Retry-After: 86400), resolve the plan state instead of retrying.
• 500 / 503 / network errors — transient. Retry with exponential backoff and jitter; honour Retry-After on 503.

Keep the same messageId across retries — the server de-duplicates on it, so a retried event won't be counted twice.

Next

• Event ingestion — the endpoint, event schema, and response shape.
• Profiles API & Consent API — the other REST endpoints (rate-limited here too).
• Event volume — batching strategy and staying under the limits at scale.

Last updated 2026-06-10