API errors use a consistent JSON envelope:
{
"message": ["Human-readable detail"],
"error": "Error name",
"statusCode": 400
}Use the HTTP status and documented endpoint contract for program logic rather
than depending on the exact wording of message.
Status codes
| Status | Meaning |
|---|---|
400 | Invalid input, unavailable operation, or invalid resource state |
401 | Missing, malformed, invalid, or organization-less API key |
404 | The documented resource was not found |
409 | The resource already exists |
429 | A request limit was reached; retry later with backoff |
500 | An unexpected server failure occurred |
Request IDs
Every response includes an x-request-id header. Record it with the request
method, path, timestamp, and status. Include it when contacting support so the
request can be traced without sharing credentials.
Retry policy
Retry 429 and transient 5xx responses with bounded exponential backoff and
jitter. Honor Retry-After when it is present.
const retryable = response.status === 429 || response.status >= 500;
const delayMs = Math.min(30_000, 500 * 2 ** attempt) + Math.random() * 250;Do not retry validation errors, authentication failures, or missing resources without changing the request or credentials.