Guides
Errors
Error format, status codes and which errors to retry.
Errors use the format of the endpoint you called.
OpenAI formats:
{"error": {"message": "not enough credits for this request. Add credits in the console", "type": "insufficient_quota", "code": "insufficient_credits"}}Messages:
{"type": "error", "error": {"type": "rate_limit_error", "message": "too many requests per minute for this key"}}| Status | Code | Retry? | What to do |
|---|---|---|---|
| 400 | invalid_request, unsupported_parameter | No | Fix the body |
| 401 | invalid_api_key | No | Check the key |
| 402 | insufficient_credits, key_budget_exceeded | No | Add credits or raise the key budget |
| 403 | key_not_allowed, account_suspended | No | Check the key's models or contact support |
| 403 | consent_required | No | The key's creator refused or withdrew consent to processing in the United States and China. They can accept it in the console |
| 404 | model_not_found, not_found | No | Check the ID |
| 413 | request_too_large | No | Send less |
| 429 | rate_limit_exceeded, concurrency_limit_exceeded, capacity_busy | Yes | Wait for retry-after seconds |
| 500 | internal_error | Yes, with backoff | Report the x-request-id if it repeats |
| 502, 504 | upstream_error, upstream_timeout | Yes, with backoff | |
| 503 | model_unavailable | Yes | Retry with backoff (retry-after is set while the service restarts) or use another model |
retry-after is in whole seconds, never more than 60. Failed requests are not charged.
Safe retries
For non-streaming requests, send an Idempotency-Key header. A retry with the same key within 24 hours returns the first response, with x-notholy-idempotent-replay: true, and is not charged again.
curl https://api.notholy.com/v1/chat/completions \
-H "Authorization: Bearer $NOTHOLY_API_KEY" \
-H "Idempotency-Key: report-42-summary" \
-H "Content-Type: application/json" \
-d '{"model": "notholy-specter", "messages": [{"role": "user", "content": "One-line summary of an open redirect."}]}'The official SDKs already retry 429 and 5xx with backoff.