Errors
Clipia API's unified error format, the table of HTTP statuses and errorCodes, and which ones are safe to retry.
Every error is returned in a single JSON shape with type, code, and a human-readable message. The HTTP status sets the error class, while the machine-readable code gives the exact reason. Only transient errors (429, 503) are safe to retry with backoff; request errors (4xx) will return the same result unless you change the request.
One unified format
Every error response shares the same shape: an error object with type, code, and message. Branch your logic on the machine-readable code, and use the HTTP status as the error class.
{
"error": {
"type": "invalid_request_error",
"code": "insufficient_credits",
"message": "Not enough credits for this generation. Please top up your balance."
}
}Error codes
| HTTP | code | When | Retry-able |
|---|---|---|---|
400 | invalid_request | Invalid body or parameters | No |
401 | invalid_api_key | Key missing, invalid, or revoked | No |
402 | insufficient_credits | Not enough credits on the balance | No — top up first |
403 | insufficient_scope | The key lacks the required scope | No |
404 | not_found | Unknown request_id or model | No |
409 | idempotency_key_reuse | Same Idempotency-Key with different parameters | No — use a new key |
409 | request_in_progress | Retry while the first request is still processing | Yes — after the first finishes |
422 | model_input_invalid | Parameters don't fit the model | No — fix the input |
429 | rate_limit_exceeded | Rate limit exceeded | Yes — after Retry-After |
500 | internal_error | Internal error | Yes — with backoff |
503 | service_unavailable | Temporarily unavailable | Yes — with backoff |
What to retry
It is safe to retry 429, 500, and 503 with exponential backoff. For 4xx request errors (except request_in_progress), retrying unchanged returns the same error — fix the request first.
Messages are sanitised
The message field never exposes internal infrastructure details. Branch on the machine-readable code, not on the message text, which may change.