> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.deepmask.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

> Understand DeepMask API error responses and error codes, learn which errors to retry and how, and see which failed requests are billed.

This page lists the errors the DeepMask API can return and how to handle each case in your code. Errors from the API endpoints share one JSON body, so your app can branch on the HTTP status and the `code` field. For the rate, size, token, and budget limits behind many of these errors, see [Limits and fair use](https://documentation.deepmask.io/api/limits.md).

## Error response format

When a request fails, the API returns an HTTP error status and this body:

```json theme={null}
{
  "error": {
    "message": "DeepMask API request could not be completed.",
    "type": "api_error",
    "code": "API_MODEL_NOT_ALLOWED"
  }
}
```

| Field | Value |
| - | - |
| `error.message` | The same text for every error: "DeepMask API request could not be completed." |
| `error.type` | Always `api_error`. |
| `error.code` | A code from the tables on this page. Use it to decide what to do. |

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](https://documentation.deepmask.io/api/chat-completions.md).

> [!TIP]
>
> Always check `error.code`, not only the HTTP status. Some codes can arrive with more than one status. For example, a spending cap refusal can be `400` or `429`.

### Errors in streamed responses

With `stream: 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.

```text theme={null}
data: {"error":{"message":"DeepMask API request could not be completed.","type":"api_error","code":"API_UPSTREAM_REJECTED"}}
```

In Python, the SDK raises a stream error as `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?](#are-failed-requests-billed) and [Unclear outcomes](https://documentation.deepmask.io/api/limits.md#unclear-outcomes).

If a streamed request reaches the [15-minute request limit](https://documentation.deepmask.io/api/limits.md#request-duration), 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

| Code | Status | What it means | What to do |
| - | - | - | - |
| `API_REQUEST_INVALID` | `400` | The body isn't valid JSON or isn't a JSON object, or `Content-Type` isn't `application/json`. The body is compressed, which means its `Content-Encoding` is anything other than `identity`, such as `gzip`, `deflate`, or `br`. `model` is missing or isn't a string. A string contains invalid Unicode, such as an unpaired UTF-16 surrogate. `user` contains the NUL character (`U+0000`). | Fix the request, for example by sending the body uncompressed. Don't retry it unchanged. |
| `API_REQUEST_INVALID` | `413` | The request body is larger than 32 MiB. | Send a smaller request. See [Request body and payload size](https://documentation.deepmask.io/api/limits.md#request-body-and-payload-size). |
| `API_REQUEST_UNBOUNDED` | `400` | The request contains a field or value the API doesn't accept. Examples are fields such as `response_format`, `logprobs`, `logit_bias`, and `reasoning_effort`, and an `n` value other than 1 or `null`. You also get this code for a sampling option outside its accepted range, such as a `temperature` above 2 or more than four `stop` sequences. The same applies to a `max_tokens` value above the model's limit or a `tool_choice` value the model doesn't support. It also applies when messages, tool definitions, `tool_choice`, and `stop` together exceed 32 MiB, even if the body itself is smaller. In messages, you get it for a part that's neither a text part nor an image part, such as a file, audio, or document part. DeepMask checks any part with an `image_url` field as an image part. You also get this code for text parts in an `assistant` or `tool` message, an empty `content` array, or `cache_control` on a text part. | Remove or change the field. See [Request body](https://documentation.deepmask.io/api/chat-completions.md#request-body) and [Sampling options](https://documentation.deepmask.io/api/chat-completions.md#sampling-options) for the accepted fields and ranges, [Messages](https://documentation.deepmask.io/api/chat-completions.md#messages) for content parts, and [Models](https://documentation.deepmask.io/api/models.md#available-models) for per-model limits. For the size limit, see [Request body and payload size](https://documentation.deepmask.io/api/limits.md#request-body-and-payload-size). |
| `API_IMAGE_INPUT_UNSUPPORTED` | `400` | The request contains an image, but the model doesn't accept images. You also get this code for an image in a message other than a `user` message. DeepMask checks the shape of each image part before it checks the model. On a model without image input, a link therefore still returns `API_IMAGE_URL_UNSUPPORTED`. An image part with the wrong keys or a `detail` value other than `"auto"` or `"low"` still returns `API_IMAGE_INVALID`. So does a data URL in the wrong form, such as one with an unsupported format or line-wrapped base64. | Use `gpt-4o`, `gpt-4.1`, `haiku-4.5`, `sonnet-4.5`, `opus-4.5`, `opus-4.6`, or `sonnet-4.6`, and send images only in `user` messages. If your key has none of these models, create a key that includes one. See [Image input](https://documentation.deepmask.io/api/chat-completions.md#image-input). |
| `API_IMAGE_URL_UNSUPPORTED` | `400` | An image is given as a link, such as an `https://` URL. DeepMask doesn't download images. | Download the image in your app, encode it as base64, and send it as a data URL, for example `data:image/png;base64,...`. The model must also accept images. See [Image input](https://documentation.deepmask.io/api/chat-completions.md#image-input). |
| `API_IMAGE_INVALID` | `400` | An image part is malformed or over a limit. Examples are invalid or line-wrapped base64, an unsupported format such as SVG or HEIC, a declared type that doesn't match the image, a `detail` value other than `"auto"` or `"low"`, and extra keys in the image part, such as `cache_control`. You also get this code for more than 20 images or 20 MB of images in total, or for an image over the model's size limit or 8,000 pixels per side. | Fix the image part. See [Image data](https://documentation.deepmask.io/api/chat-completions.md#image-data) and [Image limits](https://documentation.deepmask.io/api/chat-completions.md#image-limits). |

### 401: invalid credentials

| Code | What it means | What to do |
| - | - | - |
| `API_CREDENTIAL_INVALID` | The `Authorization` header is missing, malformed, or sent more than once. Or the key is unknown, mistyped, or no longer active, for example because it was revoked. | Send exactly one `Authorization: Bearer <key>` header, with `Bearer` written as shown. Check that you copied the whole key. If the key was revoked, create a new one. See [API keys](https://documentation.deepmask.io/api/keys.md). |

### 402: payment required

| Code | What it means | What to do |
| - | - | - |
| `API_PAYMENT_FAILED` | An API invoice payment failed, so API access is blocked for your organization. If the failed payment also made the API subscription past due, requests get `403` with `API_SUBSCRIPTION_INACTIVE` instead. | An admin pays the unpaid invoice from the **Invoices** list on the **Billing** tab: **Pay invoice** for an open invoice, or **View invoice** for one marked **Uncollectible**. Access comes back automatically, usually within about a minute. The admin can also click **Refresh** to check again sooner. See [Billing](https://documentation.deepmask.io/api/billing.md). |

### 403: access refused

| Code | What it means | What to do |
| - | - | - |
| `API_SUBSCRIPTION_INACTIVE` | Your organization isn't on an active paid plan (Pro, Power, or Enterprise), or API billing isn't active. This includes organizations on the Free plan, API billing that ended after a cancellation, and an API subscription that is past due. | An admin checks the status on the **Billing** tab. Click **Enable API billing** if API billing has ended, or pay any open invoice. If the page shows "API access needs an active paid Chat plan.", click **Chat billing**. After finishing checkout, click **Refresh**. |
| `API_CHAT_INELIGIBLE` | Rare. Your paid plan stopped being active while the request was being processed. Requests after that return `API_SUBSCRIPTION_INACTIVE`. | Same as `API_SUBSCRIPTION_INACTIVE`. |
| `API_MODEL_NOT_ALLOWED` | The key can't use this model. The model ID may be misspelled, the model may not be granted to the key, or the model may no longer be available. | Use the exact **API model ID** from the **Models** tab. Call `GET /v1/models` to list the models your key can use. A key's models can't be changed, so create a new key that includes the model. |
| `API_PRICING_MISMATCH`, `API_DEPLOYMENT_NOT_READY`, `API_DEPLOYMENT_NOT_ADMITTED` | The model is briefly unavailable, for example for up to about a minute after its price changes. You aren't billed. | Retry after a minute, or use another model. If it lasts, [contact support](https://documentation.deepmask.io/support/contact.md). The OpenAI SDKs don't retry `403` responses for you. |

### 404: endpoint not found

| Code | What it means | What to do |
| - | - | - |
| `API_ENDPOINT_NOT_FOUND` | The path or method isn't supported. Examples are `/v1/responses`, `/v1/images/generations`, `GET /v1/models/{model}`, or a path with a trailing slash or different capitalization. | Use `POST /v1/chat/completions` or `GET /v1/models`, spelled exactly as shown. |

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

| Code | What it means | What to do |
| - | - | - |
| `API_ACCOUNT_BUSY` | DeepMask couldn't process the request in time because your organization's API account was busy, usually with several requests arriving at the same moment. | Retry after a short wait. The OpenAI SDKs retry `409` automatically. |
| `API_SUPPLIER_RATE_UNVERIFIED`, `API_RATE_TIER_UNVERIFIED`, `API_FX_RATE_UNVERIFIED`, `API_BILLING_UNIT_UNVERIFIED`, `API_BILLING_UNIT_UNPRICED` | DeepMask couldn't confirm the model's current price, so it didn't run the request. You aren't billed. | Retry later, or use another model. If it lasts, [contact support](https://documentation.deepmask.io/support/contact.md). |

### 429: rate and capacity limits

| Code | What it means | What to do |
| - | - | - |
| `API_RPM_LIMIT` | Your organization reached its [**Requests per minute**](https://documentation.deepmask.io/api/limits.md#requests-per-minute) limit. All keys count together. | Slow down and retry with backoff. |
| `API_TPM_LIMIT` | Your organization reached its [**Tokens per minute**](https://documentation.deepmask.io/api/limits.md#token-throughput) limit. See [How tokens per minute works](https://documentation.deepmask.io/api/limits.md#how-tokens-per-minute-works). | Run fewer requests in parallel, then retry with backoff. |
| `API_CONCURRENCY_LIMIT` | Your organization already has as many requests running as its [**Concurrent requests**](https://documentation.deepmask.io/api/limits.md#concurrent-requests) limit allows, or this key already has 8 requests in flight. You also get this code when this key's request bodies in flight would total more than 64 MiB. See [Per-key requests in flight](https://documentation.deepmask.io/api/limits.md#per-key-requests-in-flight). Many requests from your organization that arrive at the same moment can also get this code, even below your limit. | Wait for running requests to finish, then retry. Limit how many requests your app runs in parallel, especially large ones such as requests with images. |
| `API_RATE_LIMIT` | This key reached its [flood guard](https://documentation.deepmask.io/api/limits.md#per-key-flood-guard), your organization's request or token volume reached its limit, or the model provider is limiting requests. See [Requests per minute](https://documentation.deepmask.io/api/limits.md#requests-per-minute) and [Token throughput](https://documentation.deepmask.io/api/limits.md#token-throughput). | Retry with backoff. If the response has a `Retry-After` header, wait at least that many seconds. |
| `API_MODEL_CAPACITY` | The model is at its [capacity limit](https://documentation.deepmask.io/api/limits.md#model-capacity), which is shared by all organizations that use it through the API. Your own limits aren't the cause. | Retry with backoff, or switch to another model your key can use. |

See [Limits and fair use](https://documentation.deepmask.io/api/limits.md) for the default values and how each limit works.

### Spending caps: 400 or 429

| Code | What it means | What to do |
| - | - | - |
| `API_SPENDING_CAP` | Your organization reached its **Gateway spending cap**. This is the organization-wide cap shared by all your keys. | An admin raises the cap on the **Billing** tab, or you wait for the reset at 00:00 UTC on the 1st. The cap can't go above the maximum cap shown under the field (€500 by default). To go higher, [contact support](https://documentation.deepmask.io/support/contact.md). |
| `API_KEY_SPENDING_CAP` | This key reached its **Key spending cap**. Your other keys keep working. | An admin raises or removes the key's cap with **Edit spending cap**, or you wait for the reset. |

A cap refusal can arrive with status `400` or `429`. Retrying doesn't help until the cap changes or resets. See [Spending caps](https://documentation.deepmask.io/api/spending-caps.md).

### Provider errors: 4xx, 502 or 503

| Code | Status | What it means | What to do |
| - | - | - | - |
| `API_UPSTREAM_REJECTED` | The provider's own status, usually `400` or `422` | The model provider refused the request. Common causes are a prompt longer than the model's context window, a `mistral-large-3` tool without a `description`, or a sampling value the model doesn't accept, such as a `temperature` above 1 on a model that accepts only 0 to 1. See [Options that some models ignore](https://documentation.deepmask.io/api/chat-completions.md#options-that-some-models-ignore). You aren't billed. | Fix the request, for example by shortening the prompt. Don't retry it unchanged. |
| `API_UPSTREAM_REJECTED` | `502` or `503` | The provider had a server error or was temporarily unavailable. On the Claude models, a `502` for a request with images can also mean that the provider couldn't process an image, as described below this table. | Retry with backoff, or use another model. You aren't billed unless the provider still reports usage for the request. See [Are failed requests billed?](#are-failed-requests-billed). |

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](https://documentation.deepmask.io/support/contact.md) 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

| Code | Status | What it means | What to do |
| - | - | - | - |
| `API_ADMISSION_UNAVAILABLE` | `503` | DeepMask can't accept requests for your organization right now. This can be a temporary service problem, or a recent change to your organization's API account is still being applied. Your organization's requests can also be paused while DeepMask checks recent usage. | Retry with backoff. An admin checks the **API** settings page for a notice. If requests are paused while recent usage is reviewed, see [When requests are paused](#when-requests-are-paused). If it lasts, [contact support](https://documentation.deepmask.io/support/contact.md). |
| `API_ACCOUNTING_REVIEW` | `503` | Your organization's requests are paused while DeepMask checks recent usage. Most requests during a pause return `API_ADMISSION_UNAVAILABLE` instead. This code appears only for a request that was already being processed when the pause began. | Don't retry in a loop. If the pause lasts more than a few minutes, [contact support](https://documentation.deepmask.io/support/contact.md). See [When requests are paused](#when-requests-are-paused). |
| `API_RESERVATION_REVIEW` | `503` | Your organization's requests are about to pause, or are paused, while DeepMask checks a recent request or its usage. | Handle it like `API_ACCOUNTING_REVIEW`. See [When requests are paused](#when-requests-are-paused). |
| `API_INFERENCE_UNAVAILABLE` | `503` or `504` | DeepMask couldn't get a response from the model. `504` means the request reached the [15-minute request limit](https://documentation.deepmask.io/api/limits.md#request-duration). | Retry with backoff. For `504`, ask for a shorter response or split the task into smaller requests. You aren't billed unless the model provider still reports usage for the request. See [Are failed requests billed?](#are-failed-requests-billed). |
| Other `503` codes | `503` | A temporary condition on DeepMask's side, such as a recent change to your organization's API account that is still being applied. | Retry later. If it lasts, [contact support](https://documentation.deepmask.io/support/contact.md). |

> [!NOTE]
>
> 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](https://documentation.deepmask.io/support/contact.md) if the error lasts.

## Retrying failed requests

### Which errors to retry

| Status | Retry? | What to do |
| - | - | - |
| `400`, `413`, `422` | No | Fix the request first. For spending cap codes, raise the cap or wait for the reset. |
| `401`, `402`, `404` | No | Fix the key, the path, or your API billing. If the code is `API_UPSTREAM_REJECTED`, the status came from the model provider, so retry later. |
| `403` | Only for temporary codes | Retry `API_PRICING_MISMATCH`, `API_DEPLOYMENT_NOT_READY`, and `API_DEPLOYMENT_NOT_ADMITTED` after a minute. Don't retry other `403` codes until you fix the cause. |
| `409` | Yes | Retry after a short wait. |
| `429` | Yes, with backoff | Retry with backoff, except for spending cap codes. |
| `502`, `503`, `504` | Yes, with backoff | If the error lasts, check the **API** settings page for a notice and [contact support](https://documentation.deepmask.io/support/contact.md). Don't resend a request in a loop when it keeps failing with `502` or `504`. Such a failure usually has an unclear outcome, and more than 20 of them in 24 hours pause your organization's requests. A run of `503` responses with `API_ADMISSION_UNAVAILABLE` can mean that your requests are paused. See [When requests are paused](#when-requests-are-paused). A `502` for a request with images can also mean that the provider couldn't process an image. See [Provider errors](#provider-errors-4xx-502-or-503). |

### Retries in the OpenAI SDKs

The OpenAI SDKs for Python and Node.js automatically retry `409`, `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](https://documentation.deepmask.io/api/limits.md#unclear-outcomes).

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](https://documentation.deepmask.io/api/limits.md#request-duration), 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:

1. Wait about one second before the first retry.
2. Double the wait after each failed attempt, up to a maximum such as 30 seconds.
3. Add a random amount to each wait, so parallel clients don't retry at the same moment.
4. Stop after a few attempts and report the error.

When a response includes a `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](https://documentation.deepmask.io/api/limits.md#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 check `error.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.

```bash cURL theme={null}
curl -sS -w '\nHTTP status: %{http_code}\n' 'https://api.deepmask.io/v1/chat/completions' \
  -H "Authorization: Bearer $DEEPMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'
```

```python Python theme={null}
import os
from openai import OpenAI, APIError

client = OpenAI(
    base_url="https://api.deepmask.io/v1",
    api_key=os.environ["DEEPMASK_API_KEY"],
    max_retries=4,  # Retries 409, 429 and 5xx responses with backoff
    timeout=960,  # Seconds; above DeepMask's 15-minute limit
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}],
    )
    print(response.choices[0].message.content)
except APIError as error:
    # The message is always the same. Use the status and the code.
    # A stream error has a code but no status code.
    if error.code in ("API_SPENDING_CAP", "API_KEY_SPENDING_CAP"):
        print("Spending cap reached. Raise the cap or wait for the reset.")
    else:
        print(f"Request failed: {getattr(error, 'status_code', None)} {error.code}")
```

```javascript Node.js theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepmask.io/v1",
  apiKey: process.env.DEEPMASK_API_KEY,
  maxRetries: 4, // Retries 409, 429 and 5xx responses with backoff
  timeout: 960_000, // Milliseconds; above DeepMask's 15-minute limit
});

try {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  });
  console.log(response.choices[0].message.content);
} catch (error) {
  if (!(error instanceof OpenAI.APIError)) throw error;
  // The message is always the same. Use the status and the code.
  if (error.code === "API_SPENDING_CAP" || error.code === "API_KEY_SPENDING_CAP") {
    console.error("Spending cap reached. Raise the cap or wait for the reset.");
  } else {
    console.error(`Request failed: ${error.status} ${error.code}`);
  }
}
```

> [!WARNING]
>
> If your app disconnects or times out while a request is running, DeepMask still completes the request and bills it. A retry then runs as a new request and is billed too. The original request also keeps counting toward your **Concurrent requests** limit and the key's 64 MiB of request bodies in flight until it finishes. A retry sent right after a timeout can therefore be refused with `429` and `API_CONCURRENCY_LIMIT`. Set your client timeout long enough for your longest responses.

## Are failed requests billed?

| Situation | Billed? |
| - | - |
| DeepMask refuses the request before the model runs. This covers authentication, access, request format, image, rate limit, capacity, and spending cap errors. | No |
| The provider refuses the request as invalid before producing output, for example because the prompt is longer than the context window or the provider can't process an image. | No |
| The request completes, including a response that ends with `finish_reason: "content_filter"`. | Yes |
| Your app disconnects or times out after DeepMask sent the request to the model. The request still completes. | Yes |
| Your app disconnects before DeepMask sends the request to the model. | No |
| The outcome is unclear: the model provider had a server error or timed out, the request reached the 15-minute limit, or the stream broke off midway on DeepMask's or the provider's side. | No, unless usage for the request still arrives later. Above 20 unclear outcomes in 24 hours, DeepMask checks each further one first. |

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](#when-requests-are-paused).

Above the 24-hour allowance of 20 unclear outcomes, your organization's requests pause. See [Unclear outcomes](https://documentation.deepmask.io/api/limits.md#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](https://documentation.deepmask.io/api/limits.md#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.

During a pause, requests from all your keys return `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](https://documentation.deepmask.io/api/usage-and-logs.md#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](https://documentation.deepmask.io/support/contact.md) if your requests stay paused. Don't retry in a loop while requests are paused. For other causes, [contact support](https://documentation.deepmask.io/support/contact.md) 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 returns `401` 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](https://documentation.deepmask.io/api/chat-completions.md#sampling-options) and [Options that some models ignore](https://documentation.deepmask.io/api/chat-completions.md#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](https://documentation.deepmask.io/api/chat-completions.md#unsupported-parameters).

**You get frequent `429` errors with `API_CONCURRENCY_LIMIT`?** Your app runs more requests in parallel than your organization's [**Concurrent requests**](https://documentation.deepmask.io/api/limits.md#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](https://documentation.deepmask.io/api/limits.md#per-key-requests-in-flight). Reduce parallelism, as shown in [Limit parallel requests in your app](https://documentation.deepmask.io/api/limits.md#limit-parallel-requests-in-your-app). To ask for a higher limit, see [Requesting higher limits](https://documentation.deepmask.io/api/limits.md#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](https://documentation.deepmask.io/api/chat-completions.md#image-input) and [Image data](https://documentation.deepmask.io/api/chat-completions.md#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](https://documentation.deepmask.io/api/limits.md#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](https://documentation.deepmask.io/support/contact.md). See [When requests are paused](#when-requests-are-paused).

## Related pages

> [card] [Chat completions](https://documentation.deepmask.io/api/chat-completions.md)
>
> Request format, accepted fields, image input, streaming, and tool calling.

> [card] [Limits and fair use](https://documentation.deepmask.io/api/limits.md)
>
> Rate, token, and budget limits, and how to ask for higher ones.

> [card] [Spending caps](https://documentation.deepmask.io/api/spending-caps.md)
>
> Limit monthly spend for your organization and for each key.

> [card] [Usage and logs](https://documentation.deepmask.io/api/usage-and-logs.md)
>
> See your API limits, review requests, and export a CSV.

> [card] [API keys](https://documentation.deepmask.io/api/keys.md)
>
> Create, review, and revoke keys and choose their models.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.