Documentation menu
Errors
Every error (except 429) uses one envelope with a stable machine-readable code. Branch on error.code, show error.message to humans.
The error envelope
{
"success": false,
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Event quota reached for your plan.",
"details": { "resource": "events", "limit": 20, "current": 20 }
}
}| Field | Type | Required | Description |
|---|---|---|---|
| success | boolean | required | |
| error | object | required |
Status codes and error codes
| Status | Codes | Meaning |
|---|---|---|
| 400 | BAD_REQUEST, VALIDATION_ERROR, INVALID_ID, INVALID_ORG_ID, INVALID_USER_ID, INVALID_ROLE, INVALID_STATUS, INVALID_DEPARTMENT, INVALID_USER_GROUP, MISSING_CREDENTIALS, MISSING_REFRESH_TOKEN | The request itself is malformed — fix before retrying. |
| 401 | UNAUTHENTICATED, INVALID_TOKEN, INVALID_CREDENTIALS, AUTH_FAILED, IDENTITY_UNRESOLVED | Missing/expired/invalid token or bad login. Refresh the token or re-authenticate. |
| 402 | QUOTA_EXCEEDED | Plan quota reached. details carries {resource, limit, current}. |
| 403 | FORBIDDEN, INSUFFICIENT_ROLE, ORG_CONTEXT_REQUIRED, ORG_ACCESS_DENIED, ORG_SCOPE_VIOLATION, NO_ORGANIZATION, USER_DEACTIVATED | Authenticated but not allowed — wrong role or org context. |
| 404 | NOT_FOUND, EVENT_NOT_FOUND, RECORD_NOT_FOUND, USER_NOT_FOUND, SUPPLIER_NOT_FOUND, ORGANIZATION_NOT_FOUND, RESULT_NOT_FOUND, INDUSTRY_TYPE_NOT_FOUND, SUPPLIER_NOT_ASSIGNED_TO_EVENT | Doesn't exist — or exists in another org (cross-org reads 404, never 403). |
| 409 | CONFLICT, EMAIL_ALREADY_IN_USE, SUPPLIER_ALREADY_EXISTS, SUPPLIER_EVENT_ALREADY_EXISTS, SUPPLIER_DISABLED, SUPPLIER_NOT_DISABLED, CANNOT_DELETE_SELF, CANNOT_DELETE_LAST_ADMIN, CANNOT_CHANGE_SELF | The operation contradicts current state. |
| 429 | (rate limiter) | Too many requests — see Rate limits. Body is NOT the standard envelope. |
| 503 | SERVICE_UNAVAILABLE, AUTH_PROVIDER_UNAVAILABLE | Upstream dependency unreachable — retry with backoff. |
Branch on code, not message: Messages are human-readable and may change; codes are the contract. New codes may be added over time — treat unknown codes under a status as the generic case for that status.