Error codes reference
Error response format, API error codes, and common HTTP status codes.
The API uses conventional HTTP status codes: 2xx means success, 4xx means something is wrong with the request (fix and retry), 5xx means something went wrong on our side (safe to retry with backoff). Every error response carries the same JSON envelope with a stable machine-readable code, a human-readable message and, where useful, a details object pointing at the offending field.
Error response format
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Email is required",
"details": {
"field": "email"
}
}
}Error codes
VALIDATION_ERRORInvalid input data. Check the request body and parameters.
AUTHENTICATION_ERRORInvalid or missing authentication token. Re-authenticate and try again.
AUTHORIZATION_ERRORYou don't have permission to access this resource.
NOT_FOUNDThe requested resource was not found.
CONFLICT_ERRORResource already exists or conflicts with another resource.
RATE_LIMIT_ERRORToo many requests. Wait and retry with exponential backoff.
INTERNAL_ERRORServer error. Try again later or contact support.
EXTERNAL_SERVICE_ERRORExternal service (OpenAI, AWS) is unavailable. Try again later.
SERVICE_UNAVAILABLEService temporarily unavailable for maintenance.
Recommended retry strategy
code, not by matching message text - messages can change, codes will not. Retry RATE_LIMIT_ERROR and 5xx responses with exponential backoff (for example 1s, 2s, 4s, up to 5 attempts). Never retry VALIDATION_ERROR or AUTHENTICATION_ERROR unchanged; fix the request first.