code field. For the rate, size, token, and budget limits behind many of these errors, see Limits and fair use.
Error response format
When a request fails, the API returns an HTTP error status and this body:
The body has no
param field and no details about which part of the request caused the error. To find the cause, compare your request with Chat completions.
Errors in streamed responses
Withstream: true, where the error appears depends on when it happens:
- Before the stream starts: you get a normal JSON error with an HTTP error status, as shown above.
- After the stream starts: the HTTP status is already
200, so the error arrives as an event in the stream. The OpenAI SDKs raise it as an error while you read the stream.
APIError with code set but no status code, so catch APIError, not only APIStatusError. In Node.js, error.status is undefined for a stream error.
An error during a stream usually has the code API_UPSTREAM_REJECTED. You may also see API_USAGE_IDENTITY_UNVERIFIED, which means DeepMask stopped a stream it couldn’t verify. In both cases, part of the response may already have been generated, so the request has an unclear outcome. DeepMask doesn’t charge for it unless usage for it still arrives later. On its own, it usually doesn’t pause your organization’s requests. Don’t resend the request in a loop. More than 20 unclear outcomes in 24 hours pause your organization’s requests. See Are failed requests billed? and Unclear outcomes.
If a streamed request reaches the 15-minute request limit, DeepMask closes the connection without an error event. With cURL or another HTTP client, the stream ends without data: [DONE]. The OpenAI SDKs handle data: [DONE] themselves and never show it to you. With them, reading the stream raises a connection error or ends early. Either way, check that the stream included a chunk with a finish_reason, and treat a stream without one as incomplete. A stream cut off this way also has an unclear outcome. DeepMask doesn’t charge for it unless usage for it still arrives later.
Error codes
The tables below are grouped by HTTP status.400 and 413: invalid request
401: invalid credentials
402: payment required
403: access refused
404: endpoint not found
A request to a path outside
/v1/, including /v1 on its own, returns 404 with an empty body instead of JSON. Check that your base URL is https://api.deepmask.io/v1.
409: retry shortly
429: rate and capacity limits
See Limits and fair use for the default values and how each limit works.
Spending caps: 400 or 429
A cap refusal can arrive with status
400 or 429. Retrying doesn’t help until the cap changes or resets. See Spending caps.
Provider errors: 4xx, 502 or 503
With
API_UPSTREAM_REJECTED, a 401, 403, or 404 status comes from the model provider, not from your key or path. Retry later, or contact support if it lasts.
The provider can also refuse an image it can’t process, for example a GIF it can’t decode. You aren’t billed, and the refusal doesn’t count as an unclear outcome. On gpt-4o and gpt-4.1, the status is the provider’s own 4xx status. On the Claude models, it can also be 502, which the OpenAI SDKs retry automatically. Retrying the same image doesn’t help. If a request with an image keeps failing with API_UPSTREAM_REJECTED, check the image, for example by converting it to a still PNG.
503 and 504: temporarily unavailable
If you get a code that isn’t listed here, handle it by its HTTP status. Retry
409, 429, and 5xx responses with backoff, and contact support if the error lasts.Retrying failed requests
Which errors to retry
Retries in the OpenAI SDKs
The OpenAI SDKs for Python and Node.js automatically retry409, 429, and 5xx responses. By default, they retry twice with exponential backoff and jitter. Set max_retries (Python) or maxRetries (Node.js) on the client to change this.
Each automatic retry is a new request. When a request fails with 502 or 504, each retry that fails the same way counts as another unclear outcome. A retried 504 can also run for another 15 minutes. With max_retries=4, as in the examples below, one call can therefore count up to five times toward your 24-hour allowance.
The SDKs retry every 429 response, including spending cap refusals. A capped request may therefore be retried before the error reaches your code.
The SDKs also time out after 10 minutes by default and then retry the request. A DeepMask request can run for up to 15 minutes, so set the client timeout a little above that: timeout=960 in Python (seconds) or timeout: 960_000 in Node.js (milliseconds). Otherwise the SDK can give up on a request that is still running and send it again.
Your own retry logic
If you write your own retries, use exponential backoff with jitter:- Wait about one second before the first retry.
- Double the wait after each failed attempt, up to a maximum such as 30 seconds.
- Add a random amount to each wait, so parallel clients don’t retry at the same moment.
- Stop after a few attempts and report the error.
Retry-After header, wait at least that many seconds.
To avoid 429 errors in the first place, limit how many requests your app runs in parallel. Keep it at or below your Concurrent requests value, for example with a queue or a semaphore. See Limit parallel requests in your app for examples.
Handle errors in code
The cURL example prints the HTTP status after the response body. The SDK examples set a timeout above the 15-minute request limit, retry automatically, and then checkerror.code when a request still fails. The Node.js example uses top-level await, so run it as an ES module, for example a .mjs file.
Are failed requests billed?
A request with an unclear outcome usually doesn’t pause your organization’s requests on its own. DeepMask doesn’t charge for it, but the provider may still have finished the response after the error. If usage for the request arrives later, DeepMask bills it like any other usage. A request that returned
502 or 504, or a stream that broke off, can therefore still appear in your usage. If DeepMask can’t verify that usage, for example because it’s recorded as a failed attempt, DeepMask checks it first. Your requests pause while it does. See When requests are paused.
Above the 24-hour allowance of 20 unclear outcomes, your organization’s requests pause. See Unclear outcomes.
When requests are paused
DeepMask pauses your organization’s API requests while it checks a request or recorded usage before deciding what to charge. Common causes are:- Many unclear outcomes: your organization is over its 24-hour allowance of 20 unclear outcomes. Each further one pauses your requests until DeepMask resolves it. See Unclear outcomes.
- Usage that needs checking: DeepMask can’t yet verify or price some recorded usage. Examples are usage that doesn’t match the request, usage recorded as a failed attempt, usage recorded for a request that DeepMask or the model provider refused, and usage recorded after API billing ended. Some of these checks clear on their own, for example once DeepMask confirms a model’s current price.
- Late usage: a request completed, but its usage hasn’t arrived 15 minutes after the request started. This pause clears on its own when the usage arrives.
503 with API_ADMISSION_UNAVAILABLE, or API_ACCOUNTING_REVIEW for a request that was already being processed. The API page shows “API requests are paused while recent usage is reviewed. Contact DeepMask if this lasts.”
At the very start of a pause, a request can also return 503 with API_RESERVATION_REVIEW. Handle it like API_ACCOUNTING_REVIEW.
While DeepMask checks recorded usage, the Usage tab can also show a warning such as “Requests still being checked: 2. This month’s total may change.” A pause after many unclear outcomes can also show this warning, but it doesn’t always. See Requests still being checked.
Some checks clear on their own within minutes. Others need DeepMask to resolve them. A pause after unclear outcomes over the 24-hour allowance doesn’t clear on its own, so contact support if your requests stay paused. Don’t retry in a loop while requests are paused. For other causes, contact support if the notice stays for more than a few minutes. Right after a pause ends, requests can briefly return 503 with API_ADMISSION_UNAVAILABLE while the change is applied.
Troubleshooting
Every request returns401 with API_CREDENTIAL_INVALID? Check that you send Authorization: Bearer <key> exactly once and that the key starts with sk-. Ask an admin to check the Keys tab. A revoked key appears under Revoked keys and can’t be restored, so create a new key if needed.
Requests fail right after you enabled billing? DeepMask may still be setting up your API subscription. For a short time, requests can return 403 with API_SUBSCRIPTION_INACTIVE or 503 with API_ADMISSION_UNAVAILABLE. Click Refresh on the API settings page, wait a minute, and try again.
Requests return 400 with API_REQUEST_UNBOUNDED from a framework or library? Many frameworks add parameters to every request by default. DeepMask accepts the sampling options temperature, top_p, presence_penalty, frequency_penalty, seed, and stop within their ranges, and n only as 1. Some models ignore some of them. See Sampling options and Options that some models ignore. DeepMask refuses other fields, such as response_format, reasoning_effort, and logprobs, even when they’re null or false. It also refuses an empty tools array. Configure the client to leave these out. See Unsupported parameters.
You get frequent 429 errors with API_CONCURRENCY_LIMIT? Your app runs more requests in parallel than your organization’s Concurrent requests limit allows. All keys share this limit, so check for other apps using your organization’s keys. With large requests, such as requests with images, one key can also reach its 64 MiB limit for request bodies in flight. Reduce parallelism, as shown in Limit parallel requests in your app. To ask for a higher limit, see Requesting higher limits.
Requests with images return 400? With API_IMAGE_INVALID, check that the base64 is on one line. On Linux, use base64 -w 0. Also check that the image is a PNG, JPEG, GIF, or WebP file, that the type in the data URL matches the file’s real format, and that detail is left out or set to "auto" or "low". With API_IMAGE_URL_UNSUPPORTED, send the image as a base64 data URL instead of a link. With API_IMAGE_INPUT_UNSUPPORTED, use a model with image input, such as gpt-4o, and put images in user messages. See Image input and Image data.
One model returns API_MODEL_CAPACITY while others work? That model is busy across all organizations. Retry with backoff, or switch to another model your key can use. See Model capacity.
All keys suddenly return 503? An admin checks the API settings page for a notice. If the page says requests are paused while recent usage is reviewed, DeepMask is checking a request or recorded usage. A pause can follow more than 20 502 or 504 errors or broken streams within 24 hours. Don’t retry in a loop. If the notice stays for more than a few minutes, contact support. See When requests are paused.
Related pages
Chat completions
Request format, accepted fields, image input, streaming, and tool calling.
Limits and fair use
Rate, token, and budget limits, and how to ask for higher ones.
Spending caps
Limit monthly spend for your organization and for each key.
Usage and logs
See your API limits, review requests, and export a CSV.
API keys
Create, review, and revoke keys and choose their models.