API reference

Errors

When a request fails, the API answers with an HTTP status and a JSON body that says what went wrong. This page lists every error, what it means and what to do about it.

The error body

Errors use OpenAI's format: one error object with a message for people and a code for your program. This is a 402 for a request too large for the free tier:

{
  "error": {
    "message": "This request is too large for the free tier: at most 80,000 prompt tokens (DeepSeek's count plus 10%, and 1,024 per image) and 320,000 bytes of JSON not counting image data. Send less input, or top up.",
    "type": "insufficient_quota",
    "code": "FREE_TIER_DAILY_LIMIT",
    "param": null,
    "reason": "request_too_large",
    "balance": 0
  }
}

Status and type

Each HTTP status has one type. The OpenAI libraries raise a different exception for each status:

In Python every one of them is an openai.APIStatusError; in Node.js, an OpenAI.APIError.

Errors from DeepSeek

The gateway checks a few fields itself. DeepSeek checks the rest, and when it refuses a request, its error comes back as DeepSeek sent it: the same format, with code set by DeepSeek (usually invalid_request_error) and DeepSeek's own request_id at the end of the message. This is DeepSeek's answer to "temperature": 5:

{
  "error": {
    "message": "Invalid temperature value, the valid range of temperature is [0, 2] (request_id: 6cc042c7-9847-4c53-aed8-266da6985f06)",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request_error"
  }
}

DeepSeek answers 400 for a value it refuses, and 422 for a body it can't read at all, such as an unknown role. A streamed request that DeepSeek refuses gets the same JSON error, not a stream.

Errors that aren't JSON

A few errors come from the servers in front of the API, before your request reaches it. Their body is not JSON, so check the Content-Type before you parse it:

• 413: the body is over 2 MB. nginx answers with an HTML page (below).
• 403 with the text error code: 1010: Cloudflare refused the HTTP client. This happens with Python's urllib, for example. The OpenAI libraries, curl, requests, httpx and Node.js's fetch work. See Troubleshooting and FAQ.
• A 5xx status with an HTML page, such as 502, 504 or one of Cloudflare's 52x: the servers in front of the API got no answer from it, or not in time. A 504 after 120 seconds is nginx's time limit: stream long replies, see Timeouts. Otherwise retry.

<html>
<head><title>413 Request Entity Too Large</title></head>
<body>
<center><h1>413 Request Entity Too Large</h1></center>
<hr><center>nginx</center>
</body>
</html>

Handling errors in code

This request names a model the API doesn't serve, so it fails with 400. It costs nothing and needs no balance:

curl -sS -w '\nHTTP status: %{http_code}\n' https://acacus.ly/v1/chat/completions \
  -H "Authorization: Bearer $ACACUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Say OK."}],
    "thinking": {"type": "disabled"}
  }'

The curl example prints:

{"error":{"message":"Unknown model: deepseek-chat. Model ids are exact. GET /v1/models, sent with this key, lists the models it can use: deepseek-v4-flash, deepseek-v4-pro and any others your account has.","type":"invalid_request_error","code":"MODEL_NOT_FOUND","param":"model"}}
HTTP status: 400

The Python and Node.js examples print this, with a new request id each time:

400 MODEL_NOT_FOUND invalid_request_error model
Unknown model: deepseek-chat. Model ids are exact. GET /v1/models, sent with this key, lists the models it can use: deepseek-v4-flash, deepseek-v4-pro and any others your account has.
x-request-id: a826fc60-8911-4518-be8d-2e960b80eb23

In Python, e.body holds the error object, so the details are e.body["balance"] and so on. In Node.js they are in err.error.

All errors

The code of each error, the start of its message, when it happens and what to do. Errors that come from the gateway's own checks cost nothing: see Billing and the free tier.

400 Bad request

401 Unauthorized

402 Payment required

Your balance, or the free allowance, doesn't cover the request. Every 402 has balance; some have reason and requiredLyd. How the checks work is in Billing and the free tier.

When your balance is too small for a paid request, the API tries it as a free request. That is why a 402 can carry a free-tier code while you have money in your API balance: then requiredLyd says how much balance the request needs.

403 Forbidden

404 Not found and 405 Method not allowed

413 Request too large

422 Unprocessable

429 Too many requests

The limits are explained in Rate limits and other limits.

500, 502 and 503: server errors

Retrying

• 429 rate_limit_error: wait the number of seconds in Retry-After, then retry.
• 429 concurrency_limit: retry when one of your running requests has finished.
• 500, 502, 503, and DeepSeek's own 429: retry with a growing wait. A retried UPSTREAM_INTERRUPTED is billed again, because the first try was billed for its prompt.
• Every other 4xx: fix the request first. Sent again unchanged, it gets the same error.

The OpenAI libraries retry 408, 409, 429 and 5xx errors on their own, 2 times by default, and wait the Retry-After time when there is one (checked in openai-python 3.19.2 and openai-node 7.23.0). Each retry counts toward your requests per minute. Change it with max_retries in Python or maxRetries in Node.js.

Request ids and support

Every reply from the API has an x-request-id header. Send your own x-request-id with a request and the reply carries the same value, so you can match the two in your logs. The libraries read it for you: e.request_id in Python and err.requestID in Node.js.

Replies from the servers in front of the API have no x-request-id: a 413, a 403 with error code: 1010, or a 5xx HTML page (see Errors that aren't JSON). For those, note the cf-ray header, which Cloudflare puts on every reply, and the time.

If an error doesn't make sense, write to [email protected] or on WhatsApp with the x-request-id (or the cf-ray header when there is no x-request-id), the time, and the status and body you got. Leave your API key out.