API errors

4xx/5xx responses, rate limits, idempotency and troubleshooting.

Errors

HTTP	Code	Meaning	Action
400	validation_error	The payload is valid JSON but does not follow the expected contract.	Fix the invalid fields. Reuse the same Idempotency-Key only if the mutation was not accepted.
401	unauthorized	The API key is missing, revoked, suspended or invalid.	Generate or reactivate a valid API key from the dashboard before retrying.
403	api_key_scope_required	The API key is valid but does not have the scope this endpoint requires.	Use a key with the required scope or generate a better-suited profile from the dashboard.
409	idempotency_conflict	The same Idempotency-Key was already used with a different payload.	Create a new idempotency key for this new mutation.
409	api_key_active_limit_reached	The organization already has five active API keys.	Revoke an old key before creating a new one.
429	rate_limit_exceeded	The allowed rate for this endpoint, organization and API key was exceeded in the current window.	Read Retry-After and the X-RateLimit-* headers before retrying.
500	internal_error	An unexpected error stopped processing before a stable response.	Keep the x-request-id. Replaying with the same Idempotency-Key returns the same response: check the message status before any new send.

Headers

Header	Role
x-request-id	Correlation for support, logs and client-side tracing.
X-RateLimit-Limit	Maximum capacity of the current window for the called endpoint’s bucket.
X-RateLimit-Remaining	Number of requests left before `429`.
X-RateLimit-Reset	ISO date when the window resets.
Retry-After	Present on `429` to give the recommended wait time.

429 response

http

HTTP/1.1 429 Too Many Requests
x-request-id: req_01HSQ3D6ZMBJH3J6BQ4X9G4P5R
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-18T15:31:00.000Z
Retry-After: 24
content-type: application/json

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for this API key.",
    "details": {
      "bucket": "minute",
      "retryAfterSeconds": 24
    }
  }
}

Troubleshooting

Store the x-request-id for every critical business mutation.
Treat 409 idempotency_conflict as an integration error.
On 429, use Retry-After and avoid instant loops.
On 500, only retry mutations protected by an Idempotency-Key.
Show business errors with the code and the request ID.

← Resellers Examples →