Skip to content

Menu AuthGuardHelp centre

Developers · API

API errors and request limits

1 min read
SaaS · Self-hosted

Every API route returns errors in one envelope. Use the code to decide; the message is for people only and may change.

The envelope

{"error": {"code": "validation_error", "message": "request body is invalid", "field": "body"}}

field appears when the error concerns a specific field.

Most common codes

HTTP	`code`	What to do
400	`invalid_request`, `invalid_idempotency_key`	Fix the request
401	`unauthorized`	Get a new token
403	`forbidden`, `insufficient_scope`	Missing permission or scope
404	`not_found`	The resource does not exist or belongs to another client
409	`conflict`	Idempotency or state; read the current state
422	`validation_error`, `invalid_cursor`	Fix the field; restart the list
429	`rate_limited`	Wait `Retry-After`
503	`service_unavailable`, `service_busy`	Wait `Retry-After` and retry
500	`internal_error`	Retry later; if it persists, contact support with the time

The full list, with causes and fixes, is in the error code index.

Limits (approval requests)

Per 60 seconds, per client and source network: 30 token requests, 120 creations, 600 reads and 1,200 calls in all. At most 20 pending requests per person and 1,000 per client.

How do I retry safely?

Retry only idempotent calls or calls with an Idempotency-Key.
Use jittered exponential backoff and honour Retry-After.
Never generate a new idempotency key for the same operation.
Do not retry a 4xx other than 429 without changing the request.

Error codes in this article

Article referencedev-errors-limitsquote it to support to identify this article. Checked against the product at commit 5f6607a8.