Errors and retries

Every non-2xx answer from the tenant API (/v1) has a JSON body with a human-readable message. Branch on the HTTP status, not on the text of the message. The message is meant for logs and people and can change.

The error body

There are two shapes, depending on which layer refused the request.

Gateway and search-engine operations. Authentication, key scope, plan, quota and rate-limit checks run in front of every operation. Operations forwarded to the search engine (collections, documents, searchCollection, multiSearch, …) answer in the same plain shape:

{ "message": "Forbidden - this API key may not access the collection \"orders\"." }

Some of these carry extra fields next to message:

Operations the control plane implements itself. These include events, recommendations, suggestions, experiments, connectors, assistants, voice, media and semantic or image search. They answer with a few more fields:

{
  "defined": false,
  "code": "CONFLICT",
  "status": 409,
  "message": "The experiment is already running.",
  "data": {}
}

code is a stable name for the status (BAD_REQUEST, UNAUTHORIZED, PAYMENT_REQUIRED, FORBIDDEN, NOT_FOUND, CONFLICT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR). data holds details when there are any:

The contract documents the common part: message (schema ApiResponse), plus available / requested on 402 (schema InsufficientCredits). A client that reads message works with both shapes. For the numbers, read data.available first and fall back to a top-level available.

Status codes

The API does not send 422. Validation failures are 400.

Conflicts

409 always means "not in this state". The message says which state:

Retrying

• Honour Retry-After. Every 429 from a quota or rate limit carries it, in seconds. For the monthly quota it counts down to the reset, so it can be days. Show "quota exceeded" rather than sleeping. The per-session AI allowance sends the wait in data.retry_after instead of the header.
• Back off on 500, 502 and 503. Use exponential backoff with jitter, and stop after a few attempts.
• Do not retry 400, 401, 403, 404, 411 or 413. The same request fails the same way.
• Failed requests do not use quota. Only a successful answer from the search engine counts against the monthly quota. A failed AI call costs no credits, and its reservation is released.

The generated SDKs raise a typed error for each status. By default they retry 408, 429 and 5xx with backoff and honour Retry-After.

Idempotency

A retried write can land twice if the first attempt succeeded but the response was lost. There are two protections:

• Idempotency-Key on createConnector (POST /connectors). Send a unique value, up to 255 characters. A retry with the same key and the same body returns the original response, including the connector secret that is shown only once. The same key with a different body answers 409. Other operations ignore the header.
• event_id on events. ingestEvents drops an event whose event_id it has already stored and reports it in deduplicated. A batch is safe to resend when every event has one (see events).

Other writes have no idempotency key. Before retrying a create, check whether the first attempt landed, for example with listExperiments.

Outbound event delivery has its own retry policy — six attempts with jittered backoff, and only 408, 429 and 5xx are retried. See Webhooks.