Errors
How the API reports an error, and what each code means.
The API uses the HTTP status code to tell whether a call worked. A 2xx status means it worked. A 4xx status means the call cannot succeed as it was sent. A 5xx status means something failed on the Redokun side.
Error body
Every error answer has the same JSON body:
{
"status": "error",
"error": "The API key is missing or not valid",
"code": "UNAUTHENTICATED"
}| Field | Description |
|---|---|
status | Always error, so a client can tell an error from a payload |
code | A stable identifier for the cause. Match on this |
error | What went wrong, in English. Written for a person reading a log; it can change, so do not match on it |
Error codes
| Status | Code | Message | Cause |
|---|---|---|---|
401 | UNAUTHENTICATED | The API key is missing or not valid | No key, or a key that is malformed, unknown or revoked. See Authentication |
403 | FEATURE_NOT_ENABLED | Public API access is not enabled for this team | The plan of the team does not include the API |
403 | ACCOUNT_NOT_ACTIVE | This account cannot use the API right now | The account is disabled, or the subscription of the team is suspended or expired |
403 | INSUFFICIENT_SCOPE | This API key is only allowed to read | The key is Read only and the call writes |
404 | NOT_FOUND | No endpoint matches this method and path | The path does not exist, or it exists but not with this method |
429 | RATE_LIMITED | Too many requests. Slow down and retry after the time in the Retry-After header. | The key has used up its call budget. See Rate limits |
500 | GENERIC_ERROR | An unexpected error occurred | Something failed on the Redokun side |
A wrong method on an existing path gets 404, not 405: for example, POST /v1/me.
Handling errors
| Status | What to do |
|---|---|
401, 403, 404 | Do not retry. The same call gets the same answer until you fix the key, the access or the request |
429 | Wait the number of seconds in the Retry-After header, then retry |
500 | Retry later, with a growing delay between attempts. If it keeps failing, write to support@redokun.com |