Errors

The envelope

Every non-2xx response, and every error item inside a batch 200, has the same two fields:

{ "error": "invalid_request", "message": "element and user_id are required" }

error is a stable code for your code to branch on; message is the human-readable reason, the same text this documentation quotes. Internal faults add request_id:

{ "error": "internal_error", "message": "Internal error", "request_id": "2f7e9c1a-5b3d-4e8f-9a0b-1c2d3e4f5a6b" }

Statuses

Status	Retry?	Meaning
`200`		Success. In a batch, individual items may still carry an error.
`400`	No. Fix the request.	The request is wrong. Nothing was written.
`401`	No. Fix the key.	The key is missing, malformed, unknown or revoked.
`403`	No. Use the right key or origin.	The key may not do this, or came from a disallowed origin.
`404`, `405`	No.	Wrong path or method; the data plane is four `POST` endpoints.
`409`	Only `lock_timeout`, once.	The request conflicts with current state.
`429`	After `Retry-After`.	Over the per-minute limit; `Retry-After` says how long.
`500`	`decide`: serve your fallback. `events`, `identify`: retry with the same ids.	A fault on our side, sanitized.
`502` and other `5xx`	Only with the same `idempotency_key` or `id`.	The request may or may not have been applied.

Codes

The error field carries one of these codes. Each section gives the status, what happened, and what to do.

`invalid_request`

400. A validation failure. The message names the field, with its path for nested ones (Received unknown parameter: rewards[0].window_second). Fix the field the message names. Field names are snake_case and match the contract. See A request is rejected for an unknown field.

`invalid_json`

400. The body could not be parsed (Invalid JSON body). Check the serializer and the Content-Type header.

`unauthorized`

401. Missing or invalid API key, or API key has been revoked. Send Authorization: Bearer <key> with a current key. After a rotation, deploy the new key before revoking the old.

`forbidden`

403. Origin not allowed for this key: a publishable key from an origin not on its allowlist. Or a publishable key on a secret-only endpoint: Declare requires a secret key. Add the exact https:// origin to the key in the dashboard, or use a secret key from a server.

`not_found`

404. No such path. Use /v1/decide, /v1/declare, /v1/events or /v1/identify.

`method_not_allowed`

405. Only POST is accepted. Use POST.

`conflict`

409. State conflicts with the request. Three cases: No live experiment for element "…" under a publishable key; Identity conflicts with an existing user on identify; Experiment already has 50 active arms. Declare the element with a secret key first; resolve the identity link on your side; conclude an arm before adding another. Do not retry. See The API returns 409 conflict.

`lock_timeout`

409. Identity changed during selection; retry the request: the user’s identity was being linked while this decision was selecting an arm. The one retryable 409. Retry the same request once. See The API returns 409 conflict.

`idempotency_error`

409. idempotency_key was already used with a different request. Generate a new key for a new logical request; reuse a key only for a byte-for-byte retry. See Idempotency.

`rate_limit_exceeded`

429. Over 1,000 requests per minute per endpoint for the organization. Wait Retry-After seconds, then retry with the same keys. Batch events. See Rate limits.

`internal_error`

500, 502 or another 5xx. A sanitized fault on our side, or the API edge could not complete the call. Carries request_id. For decide, serve your fallback and retry only with the same idempotency_key. For events, retry with the same id. For identify, retry the same request. Quote request_id to support.

Batch items

In a batch, a failing item is reported inside the 200 at its index with the same shape:

{ "index": 2, "element": "hero_cta", "status": "error", "error": "invalid_request", "message": "control is required when creating an experiment" }

Envelope-level errors apply to the whole request (a bad key, a malformed envelope, more items than the cap) and arrive as a non-2xx status. Item-level errors apply to one item and never fail its siblings. See Batch calls.

Ambiguous failures

A 502, any other 5xx from the API edge, or a dropped connection means the request may or may not have been applied. The message says so and names the safe retry:

The API could not be reached, and the request may or may not have been applied; retry only with the same idempotency_key (decide) or id (events)

An unkeyed retry after such a failure can duplicate the write. The server SDK therefore never retries decide, and retries events only under their stable ids.

`X-Request-Id`

Every response, success or failure, carries an X-Request-Id header: the id of that request on our side. Quote it when you contact support and we can find the exact request in our logs. Internal faults repeat it in the body as request_id. Browsers can read the header; it is exposed through CORS. The SDK surfaces it as requestId on every result and error.

In the server SDK

The SDK maps these codes and statuses onto its own stable codes with a retryable flag, and never exposes a raw body. The mapping is on Errors in the server SDK.

API reference

Endpoints