Errors
Error format, status codes, and retry guidance for Bitdeer AI APIs.
Non-2xx responses return a JSON body in the OpenAI error envelope:
application/json— Rate limitedError messages are generic by design and may change. Branch on the HTTP status, type and code, which are stable.
/v1/messages uses the Anthropic envelope instead — see Anthropic-compatible errors.
HTTP status codes
| HTTP | type | Retryable | Meaning |
|---|---|---|---|
400 | invalid_request_error | No | The body is not valid JSON, a field has the wrong type or is out of range, a media URL is not allowed, or the prompt exceeds the model's context window |
401 | authentication_error | No | The API key is missing, malformed, unknown or expired |
402 | insufficient_quota | No | The account balance does not cover the request, or it has unpaid charges — top up the account first |
403 | permission_error | No | Your account may not use the requested model, or the account is unavailable |
404 | invalid_request_error | No | No model with this code is available, or the model does not serve this endpoint |
405 | — | No | The endpoint does not accept this HTTP method; the body has only message and type |
413 | invalid_request_error | No | The request body exceeds the 32 MiB size limit |
429 | rate_limit_error | Depends on code | A rate limit (default: 100 RPM) or the API key's usage allowance was exceeded — see the codes below |
500 | server_error | Yes | Unexpected error |
501 | — | No | The Bearer token looks like a JWT, not an API key — see Authentication |
502 | server_error | Yes | An upstream dependency is temporarily unavailable |
503 | server_error | Yes | Capacity is temporarily exhausted, or the model is under maintenance — wait Retry-After seconds when present, otherwise back off |
504 | server_error | Yes | The model did not respond in time |
Error codes
code is set when there is a specific condition to report, and null otherwise.
code | Status | Description |
|---|---|---|
invalid_api_key | 401 | The API key is missing, malformed, unknown or expired |
context_length_exceeded | 400 | The prompt is longer than the model's context window |
model_not_found | 404 | No model with this code is available, or the model does not serve this endpoint |
insufficient_balance | 402 | The account balance does not cover the request |
rate_limit_exceeded | 429 | Your account exceeded one of its request or token rate limits — back off and retry |
insufficient_quota | 429 | The API key's usage allowance is used up; retrying does not help until it is raised |
maintenance | 503 | The model is under maintenance — retry later |
Rate limits
The default rate limit for all endpoints is 100 requests per minute (RPM). Rate limits apply per account, to both requests and tokens. When one is exceeded, the API returns 429 with code rate_limit_exceeded; retry with exponential backoff.
When an API key's usage allowance is used up, the API returns 429 with code insufficient_quota and these headers:
| Header | Description |
|---|---|
X-Quota-Used | Requests counted against the key's allowance |
X-Quota-Limit | The key's allowance, in requests |
Request IDs
Every response, including errors, carries an X-Request-ID header. Quote it when you contact support.
Error schema
typestringrequiredinvalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, server_error or api_error.messagestringrequiredcodestring | nullrequiredparamstring | nullrequiredAnthropic-compatible errors
/v1/messages returns errors in the Anthropic envelope, so Anthropic SDKs can parse them:
request_id has the same value as the X-Request-ID response header.
| HTTP | error.type |
|---|---|
400 | invalid_request_error |
401 | authentication_error |
402 | billing_error |
403 | permission_error |
404 | not_found_error |
413 | request_too_large |
429 | rate_limit_error |
500, 502 | api_error |
503 | overloaded_error (Anthropic itself uses 529) |
504 | timeout_error |
Last updated on