Errors
One error shape, stable types and codes, and a request id on every response.
Every non-2xx response has the same body:
{
"error": {
"type": "invalid_request",
"code": "invalid_parameter",
"message": "source: lowercase letters, digits, _ . - (max 64)",
"param": "source",
"request_id": "req_4f1c9a…"
}
}typeis the broad category — branch on this.codeis the specific reason. New codes may be added; existing ones never change meaning.paramnames the offending field when there is one.request_idis also returned in theX-Request-Idheader on every response, success or error. Include it when you contact support. You can send your ownX-Request-Id(8–128 characters of[A-Za-z0-9_.-]) to correlate with your logs.
Types
type | Status | Retry? |
|---|---|---|
invalid_request | 400, 413 | No — fix the request. |
authentication_error | 401 | No — check the key and region. |
permission_error | 403 | No — grant the permission or widen data access. |
not_found | 404 | No. |
conflict | 409 | Sometimes — see the code. |
rate_limited | 429 | Yes, after Retry-After seconds. |
api_error | 500 | Yes, with exponential backoff. |
Codes
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_json | The body is not valid JSON. |
| 400 | invalid_parameter | A parameter failed validation; param names it. |
| 400 | idempotency_key_reused | The Idempotency-Key was already used with a different request. |
| 413 | body_too_large | The request body exceeds 1 MiB. |
| 401 | missing_api_key | No Authorization: Bearer header. |
| 401 | invalid_api_key | Malformed, unknown, expired, or revoked key. |
| 401 | wrong_region | The key belongs to the other region. |
| 403 | insufficient_permissions | The key lacks the endpoint's permission. |
| 403 | visibility_not_allowed | A write asked for wider visibility than the key has. |
| 403 | not_participant | The key is not part of the requested message thread. |
| 404 | resource_missing | Not found — or outside the key's data access. |
| 404 | unknown_endpoint | No endpoint at this method and path. |
| 409 | document_not_accessible | A document with this (source, external_id) exists outside the key's data access. |
| 409 | invalid_state | The resource is not in a state that allows this change. |
| 409 | idempotency_in_progress | A request with this Idempotency-Key is still running — retry shortly. |
| 429 | rate_limit_exceeded | Too many requests. |
| 500 | internal_error | Something went wrong on our side. |