Errors
Overview
HTTP Status Codes
200er / 500er Status Codes
| HTTP Status | Error Key / Code | User-Facing Message | Description / Notes |
|---|---|---|---|
| 200 | SUCCESS | Request completed successfully. | Standard success response. Used for successful authentication actions, such as valid login, token refresh, or session check. |
| 500 | API_EXCEPTION | Something went wrong while processing your request. Please try again shortly. | Internal server error caused by service outages, backend dependency failures, or unhandled backend exceptions. Not user-resolvable; should trigger retry or error report. |
400er Status Codes
| HTTP Status | Error Key | User-Facing Message | Description / Notes |
|---|---|---|---|
| 401 | INVALID_TOKEN | Your session has expired. Please log in again. | Triggered when the provided token is invalid or has expired. Common across endpoints requiring BearerAuth. |
| 403 | USER_DEACTIVATED | Your customer account has been deactivated. If you have any questions, feel free to get in touch. | Account was blocked or deactivated; applies on login and session-authenticated calls. |
| 404 | USER_NOT_FOUND | Your email address or password is incorrect. Please try again. | Returned when login details do not match an existing user. |
| 406 | PASSWORD_RESET_HASH_EXPIRED | This link has expired or has already been used. | Specific to password reset flows; the provided reset hash is no longer valid. |
| 409 | USER_ALREADY_EXISTS | An account with this email address already exists. | Triggered when trying to register a user that already exists. |
| 429 | TOO_MANY_ATTEMPTS | You’ve made too many attempts. Please wait a moment and try again. | Rate-limiting error — typically shown after repeated failed login or sensitive action attempts. |
| 424 | API_EXCEPTION | Something went wrong while processing your request. Please try again shortly. | General dependency or backend failure -often a catch-all when external services fail. |
Schema
| Field | Type | Description |
|---|---|---|
error | string | Short technical identifier (e.g., INVALID_CLIENT, invalid_request). |
message | string | Human-readable error explanation. |
error_description | string (optional) | Extended backend description (sometimes same as message, sometimes more detailed). |
hint | string (optional) | Developer advice on fixing the issue (rarely user-facing). |
context | object or null | Optional debug context (usually null but reserved for extra info). |
Payload Example
| Error Case | Example JSON Response | Notes |
|---|---|---|
| Unauthorized Client | json { "error": "INVALID_CLIENT", "message": "Client authentication failed.", "context": null } | Happens when client ID or secret is invalid. context is usually null but may include more in the future. |
| Unsupported Grant Type | json { "error": "unsupported_grant_type", "error_description": "The authorization grant type is not supported by the authorization server.", "hint": "Check that all required parameters have been provided", "message": "The authorization grant type is not supported by the authorization server." } | The server doesn’t support the provided OAuth2 grant type (e.g., refresh_token, password, etc.). |
| Invalid Token | json { "error": "invalid_request", "error_description": "The refresh token is invalid.", "hint": "Token has been revoked", "message": "The refresh token is invalid." } | The provided token is invalid, expired, or revoked. hint gives extra developer context for debugging or fixing. |
