Errors
Non-protocol HTTP errors use a consistent snake-case envelope:
{
"timestamp": "2026-08-11T10:30:00.000Z",
"path": "/api/v1/me/profile",
"status_code": 422,
"error": "invalid_request",
"error_description": "Validation failed",
"error_uri": null,
"details": [
{
"property": "first_name",
"messages": ["first_name must be a string"]
}
]
}
OAuth endpoints use registered OAuth error names where applicable, including invalid_request, invalid_client, invalid_grant, invalid_token, invalid_target, and insufficient_scope.
Common status codes
| Status | Meaning |
|---|---|
400 | Malformed protocol request or invalid grant input. |
401 | Missing, expired, revoked, malformed, or wrong-kind bearer/client credential. |
403 | Authenticated but audience, assignment, consent, or permission is insufficient. |
404 | Resource not found; directory reads also use this for unassigned users. |
409 | State conflict or duplicate resource. |
422 | DTO validation failed; inspect details. |
429 | Throttled; retry with backoff. |
5xx | Server or upstream service failure. |
Bearer challenges
Protected APIs set WWW-Authenticate. Machine directory errors also include resource_metadata so clients can discover the correct audience and scopes.
Support correlation
Responses expose x-reference-id, using the active trace ID when available and otherwise x-request-id. Include that value, the timestamp, route, and status when contacting support. Never send tokens, secrets, passwords, or OTPs.