Guides
Errors and recovery
Use stable error codes, structured details and request identifiers to decide what to fix and when to retry.
A consistent error envelope
Errors use an error object with type, code, message, request_id and optional details. Branch on the HTTP status and stable code; treat the message as diagnostic text. Every response also has X-Request-Id. Keep that identifier when reporting a problem, while keeping keys and sensitive record payloads out of logs.
{
"error": {
"type": "validation_error",
"code": "validation_failed",
"message": "The supplied field is not available.",
"details": { "unknown": ["nname"], "nearest": { "nname": ["name"] } },
"request_id": "4d85a25f-d510-41f5-b228-32a875670fd0"
}
}Choose the right recovery
Fix invalid input and access problems before retrying. A 404 also covers a record in another workspace or a record the owner cannot see.
| Status | Codes | Recovery |
|---|---|---|
| 400 | invalid_request | Fix JSON, parameters, filters or cursor settings. |
| 401 | invalid_api_key, expired_api_key, key_assurance_stale | Check the secret, expiry and MFA; replace the key when needed. |
| 403 | ip_not_allowed, permission_denied, plan_upgrade_required, insufficient_scope, feature_unavailable, forbidden | Check server IP, membership, role, plan, key scope and workspace availability. |
| 404 | not_found, unknown_resource, route_not_found | Check the path, identifiers and the owner’s visibility. |
| 405 | method_not_allowed | Use a supported verb from the Allow header; some resources are read-only. |
| 409 | conflict, idempotency_key_in_use | Resolve the conflict, or wait before retrying the same idempotent request. |
| 413 | payload_too_large | Reduce the request body to at most 1 MiB. |
| 422 | validation_failed, idempotency_key_reused | Correct fields/types or use a new key for a different operation. |
| 429 | rate_limited, quota_exceeded | Honour Retry-After; inspect limits and the quota reset. |
| 500 / 503 | internal_error, service_unavailable | Retry with bounded backoff; preserve the write’s idempotency key. |
Use the details, not guesswork
Validation details can include unknown, nearest and alternatives, naming fields or options to correct. Pagination errors can include max_page; quota errors can include resets_at; database validation can include sqlstate and a relevant hint. Describe the resource again if the workspace schema has changed.
Retry with limits
For transient failures, use a bounded number of retries with exponential backoff and jitter. Respect Retry-After when present. Do not automatically retry a 400, 401, 403 or validation failure. Preserve the exact request and idempotency key across write retries, and reconcile uncertain outcomes before issuing a new write.