Errors

Error format, status codes, and retry guidance for Bitdeer AI APIs.

Non-2xx responses return a JSON body in the OpenAI error envelope:

429application/json— Rate limited
{
  "error": {
    "message": "rate limit exceeded",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

Error 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

HTTPtypeRetryableMeaning
400invalid_request_errorNoThe 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
401authentication_errorNoThe API key is missing, malformed, unknown or expired
402insufficient_quotaNoThe account balance does not cover the request, or it has unpaid charges — top up the account first
403permission_errorNoYour account may not use the requested model, or the account is unavailable
404invalid_request_errorNoNo model with this code is available, or the model does not serve this endpoint
405—NoThe endpoint does not accept this HTTP method; the body has only message and type
413invalid_request_errorNoThe request body exceeds the 32 MiB size limit
429rate_limit_errorDepends on codeA rate limit (default: 100 RPM) or the API key's usage allowance was exceeded — see the codes below
500server_errorYesUnexpected error
501—NoThe Bearer token looks like a JWT, not an API key — see Authentication
502server_errorYesAn upstream dependency is temporarily unavailable
503server_errorYesCapacity is temporarily exhausted, or the model is under maintenance — wait Retry-After seconds when present, otherwise back off
504server_errorYesThe model did not respond in time

Error codes

code is set when there is a specific condition to report, and null otherwise.

codeStatusDescription
invalid_api_key401The API key is missing, malformed, unknown or expired
context_length_exceeded400The prompt is longer than the model's context window
model_not_found404No model with this code is available, or the model does not serve this endpoint
insufficient_balance402The account balance does not cover the request
rate_limit_exceeded429Your account exceeded one of its request or token rate limits — back off and retry
insufficient_quota429The API key's usage allowance is used up; retrying does not help until it is raised
maintenance503The 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:

HeaderDescription
X-Quota-UsedRequests counted against the key's allowance
X-Quota-LimitThe 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

error
typestringrequired
Error category: invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, server_error or api_error.
messagestringrequired
Human-readable description of the failure. Not a stable contract.
codestring | nullrequired
Specific condition, when there is one — see Error codes.
paramstring | nullrequired
Name of the offending request field, when applicable.

Anthropic-compatible errors

/v1/messages returns errors in the Anthropic envelope, so Anthropic SDKs can parse them:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "API key invalid or expired"
  },
  "request_id": "0123456789abcdef0123456789abcdef"
}

request_id has the same value as the X-Request-ID response header.

HTTPerror.type
400invalid_request_error
401authentication_error
402billing_error
403permission_error
404not_found_error
413request_too_large
429rate_limit_error
500, 502api_error
503overloaded_error (Anthropic itself uses 529)
504timeout_error

Last updated on

On this page