Operations

Errors and retries

Use stable error codes for decisions and request IDs for support. Never expose raw server exceptions to end users.

Error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data.",
    "requestId": "7ee682ab-..."
  }
}

Status	Meaning	Action
400	Invalid request or OAuth transaction.	Correct it; do not retry unchanged.
401	Authentication is absent or invalid.	Reauthenticate once.
403	The authenticated actor lacks permission.	Check role, consent, scopes, and environment.
404	Resource is absent or intentionally hidden.	Confirm the public reference.
409	Current state conflicts with the operation.	Refresh before deciding to retry.
429	Rate limit or security attempt limit reached.	Honor backoff guidance.
500/503	Unexpected failure or dependency unavailable.	Retry idempotently with exponential backoff.

OAuth errors

invalid_client means client authentication failed. invalid_scope means a scope is unsupported or disabled. invalid_grant means the code is invalid, expired, reused, or bound to different values. These OAuth errors use the token endpoint's error and error_description response.

Application error codes

INVALID_REDIRECT_URI means the callback is not an exact registered value. It is returned through the standard API error envelope and must not be handled as a lowercase OAuth redirect error.

Safe support details

Provide the request ID, UTC time, route, HTTP status, environment, and public application ID. Exclude access tokens, client secrets, authorization codes, OTPs, documents, and claim values.

Retry design

Retry only idempotent requests automatically. Use exponential backoff with jitter and an upper bound. Never replay an authorization code or duplicate a completed side effect.