Errors
Raha Account uses standard OAuth error codes on protocol endpoints and a consistent JSON envelope on resource APIs.
OAuth errors
Protocol endpoints return registered OAuth error names in error, with a human-readable error_description.
error | Typical cause |
|---|---|
invalid_request | A required parameter is missing or malformed. |
invalid_client | Unknown client, wrong secret, or the wrong client authentication method. |
invalid_grant | Expired, used, or revoked code or refresh token, or a redirect_uri mismatch. |
invalid_target | The requested resource is unknown or not granted to your application. |
invalid_token | The bearer token is missing, expired, revoked, or for a different audience. |
insufficient_scope | The token is valid but lacks a required scope. |
access_denied | The user denied consent or the request was not permitted. |
Errors from the authorization endpoint are returned to your redirect_uri as error, error_description, and state query parameters.
Resource API errors
Resource APIs use a snake-case envelope:
{
"timestamp": "2026-08-11T10:30:00.000Z",
"path": "/api/v1/directory/users/6f1c2a4e-1b7d-4d55-9c1e-0a2b3c4d5e6f",
"status_code": 404,
"error": "user_not_found",
"error_description": "User not found.",
"error_uri": null
}
Validation failures (422) also include details, an array of { "property", "messages" } entries.
Status codes
| Status | Meaning |
|---|---|
400 | Malformed protocol request or invalid grant input. |
401 | Missing, expired, revoked, or malformed bearer token or client credentials. |
403 | Authenticated, but the audience, assignment, consent, or scope is insufficient. |
404 | Not found. The account directory also uses this for unassigned users. |
409 | Conflict with the current state. |
422 | Validation failed; inspect details. |
429 | Rate limited; retry with exponential backoff. |
5xx | Server error; retry idempotent requests with backoff. |
Bearer challenges
Protected APIs set a WWW-Authenticate header on 401 and 403 responses. Account directory errors also include resource_metadata, so clients can rediscover the correct resource and scopes.
Contacting support
Every response includes an x-reference-id header. When you contact Raha Account support, include that value with the timestamp, route, and status code. You can also send your own x-request-id header to correlate requests with your logs.
Never send tokens, client secrets, passwords, or one-time codes to support.