Error codes

The standard error envelope, what each status means, and how to respond

Every error returns the same shape. requestId matches the x-request-id response header, so quote it when reporting a problem.

1 {
2   "error": {
3     "message": "Missing required scope: update:users",
4     "status": 403,
5     "requestId": "6f1c0a3e-6d0f-4f2b-9a1e-2b7a5c0d9e11"
6   }
7 }

In non-production environments the envelope may carry a details field with validation issues or the upstream Auth0 response. It is suppressed for server errors in production.

Status codes

Status	Meaning	What to do
`400`	The request failed validation	Fix the request; `details` names the fields
`401`	Missing, expired, or invalid token	Get a new token; check the audience and tenant
`403`	Valid token without the required scope	Request the scope for the client
`404`	No such resource	Confirm the identifier and the tenant
`409`	Conflicts with an existing record	Look up the existing record first
`429`	Rate limited	Back off and retry; see Rate limits
`500`	Unhandled error in the proxy	Retry once, then report with the request id
`502`	Auth0 unreachable, or the proxy’s own credentials were rejected	Retry with backoff; escalate if it persists
`503`	The identity provider could not be reached to verify a token	Retry with backoff

A 401 from Auth0 to the proxy surfaces as 502, not 401. A 401 you receive always refers to your own token.

Which errors are worth retrying

Status	Retry	Notes
`400`, `401`, `403`, `404`, `409`	No	Retrying repeats the same failure
`429`	Yes	Honor `Retry-After`
`500`, `502`, `503`	Yes	Exponential backoff with jitter, and a cap

Common messages

Message	Cause
`Missing bearer token`	No `Authorization` header, or a malformed one
`Token expired`	The cached token outlived its lifetime
`Token claim "aud" is invalid`	Token requested for a different audience
`Missing required scope: <scope>`	The client is not granted that scope
`Request validation failed`	Body or query did not match the schema

Reporting a problem

Include the request id, the timestamp with its timezone, the environment, the method and path, and the status you received. The request id is the fastest way to find the matching log line.