> ## 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.

# Spending caps

> Limit monthly DeepMask API spend with an organization-wide gateway spending cap and optional caps for individual keys.

Spending caps limit how much your API keys can spend on model costs each month. Every organization has one **Gateway spending cap**. This is the organization-wide cap shared by all your keys. You can also give any key its own optional key spending cap, for example to keep a staging or test key well below your production budget.

You manage both caps on the **API** settings page. Only organization admins can open this page. The caps appear after you enable API billing, which needs an active paid plan (Pro, Power, or Enterprise). See [Billing](https://documentation.deepmask.io/api/billing.md).

## The two caps at a glance

| | Gateway spending cap | Key spending cap |
| - | - | - |
| **Applies to** | All keys in your organization combined | One key |
| **Required** | Always set. The default is €100. | Optional. New keys have no cap unless you set one. |
| **Highest value** | The maximum cap shown under the field (€500 by default) | The current **Gateway spending cap** |
| **Where to set it** | **Billing** tab (**Manage cap** on the **Usage** tab takes you there) | **Create API key** dialog, or **Edit spending cap** in the key's menu |
| **What it counts** | Model costs before the 3% fee and tax | Model costs before the 3% fee and tax |
| **Resets** | Monthly, at 00:00 UTC on the 1st | Monthly, at 00:00 UTC on the 1st |
| **When it is reached** | Requests from every key are refused with `API_SPENDING_CAP` | Requests from that key are refused with `API_KEY_SPENDING_CAP` |
| **Request log status** | **Blocked: gateway cap** | **Blocked: key cap** |

For how spending caps fit with the other API limits, such as rate and token limits, see [Budget limits](https://documentation.deepmask.io/api/limits.md#budget-limits).

## What a cap counts

A cap measures the model costs of your requests, without the 3% fee and without tax. A €100 cap therefore allows about €100 of model costs in a month. If you use exactly that amount, your invoice shows about €103 before tax. See [Billing](https://documentation.deepmask.io/api/billing.md) for how invoices are calculated.

The prices on the **Models** tab already include the 3% fee. At those prices, a €100 cap covers about €103 of usage. See [Models](https://documentation.deepmask.io/api/models.md) for how pricing works.

The **Monthly API charges** figure on the **Usage** tab also includes the fee. For a rough idea of how much of your **Gateway spending cap** you have used, divide that figure by 1.03. This is a lower estimate. Requests that are still being priced or checked count toward the cap before they appear in **Monthly API charges**. While some requests are still being checked, the **Monthly API charges** card shows a "Requests still being checked" notice. The **Gateway spending cap** card itself shows the cap and its reset date, not your spend against it.

## Gateway spending cap

The **Gateway spending cap** applies to the combined spend of every key in your organization. It appears on the **Usage** and **Billing** tabs after you click **Enable API billing** for the first time. New organizations start with a cap of €100.

The highest cap you can choose is shown under the field as **Maximum cap**. By default, this is €500. To raise the maximum cap for your organization, [contact support](https://documentation.deepmask.io/support/contact.md).

### Change the gateway spending cap

**1. Open the Billing tab**

Click your name at the bottom of the chat sidebar, choose **User Settings**, click **API** in the settings sidebar, and select the **Billing** tab. You can also click **Manage cap** on the **Gateway spending cap** card in the **Usage** tab, which opens the **Billing** tab with the cap field ready.

**2. Enter the new amount**

Type an amount in euros with up to two decimal places, such as `250` or `250.50`. You can use a comma or a period as the decimal mark. The amount must be more than zero and no higher than the maximum cap.

**3. Save**

Click **Save cap**. A **Spending cap saved** confirmation appears, and the new cap applies to the next requests.

**Save cap** stays disabled until you change the amount. If the value is not accepted, the field shows one of these messages:

* "Enter a positive amount in EUR with up to two decimal places."
* "The cap can’t be more than €500.00." The amount shown is your maximum cap.

### Monthly reset

The cap resets at 00:00 UTC on the 1st of every month. Your spend then starts again from zero. The reset can take effect a few minutes after midnight.

Your first period is shorter than a full month. It runs from when you first enabled API billing until the next 1st. The **Billing** tab shows the next reset date next to the cap, for example **Resets Dec 1, 2026.**

> [!NOTE]
>
> Dates on the API page use your browser's time zone. If you are west of UTC, a reset at 00:00 UTC on the 1st can show as the last day of the previous month.

### Change the cap during a month

Changing the cap keeps your spend so far and keeps the same reset date. It does not start a new period.

* **Raising the cap** gives you more room for the rest of the month. If requests were being refused, they can go through again.
* **Lowering the cap below what you have already spent** blocks further requests. They stay blocked until the cap resets on the 1st or until you raise it again.

> [!WARNING]
>
> A cap is not a strict maximum for your invoice. Requests are refused once spend is over the cap. Requests that are already running, requests sent at the same time, and costs that are recorded with a short delay can take spend slightly over the cap.

## Key spending caps

A key spending cap limits what a single key can spend on model costs each month. The **Gateway spending cap** still applies to that key as well. Use key caps to stop one app, environment, or experiment from using up your whole organization budget.

### Set a cap when you create a key

In the **Create API key** dialog, enter an amount under **Key spending cap (optional)**. Leave the field empty to rely on the **Gateway spending cap** only. See [API keys](https://documentation.deepmask.io/api/keys.md) for the full key creation flow.

### Add, change, or remove a key cap

**1. Open the key's menu**

On the **Keys** tab, click the **⋮** menu on the key's row, then click **Edit spending cap**.

**2. Enter the cap**

Type an amount in euros in the **Cap (EUR)** field, with up to two decimal places.

**3. Save**

Click **Save cap**. A **Key spending cap saved** confirmation appears.

To remove a key's cap, open **Edit spending cap** and click **Remove cap**. Saving an empty field also removes the cap. A **Key spending cap removed** confirmation appears, and the key is then limited by the **Gateway spending cap** only.

![Key spending cap dialog for a key named Staging, with a €25.00 amount in the Cap (EUR) field and Cancel, Remove cap, and Save cap buttons.](https://mintcdn.com/deepmaskgmbh/Tc7tJrGOE8MSnXNJ/images/api/key-cap.jpg?fit=max\&auto=format\&n=Tc7tJrGOE8MSnXNJ\&q=85\&s=010f801137b10b295bf1f0a5ce01b497)

Set, change, or remove the spending cap for one key.

> [!NOTE]
>
> **Edit spending cap** is unavailable while a key shows **Pending** or **Revoking**. Revoked keys can't have a cap.

### Rules for key caps

* A key cap uses the same format as the **Gateway spending cap**: a positive amount in euros with up to two decimal places.
* A key cap can't be higher than your current **Gateway spending cap**. If you enter a higher amount, you see "A key cap can’t be more than the gateway spending cap (€100.00)." The amount in parentheses is your current **Gateway spending cap**. When you edit a key's cap, **Save cap** stays disabled until you enter a lower amount.
* Each key cap is checked against the **Gateway spending cap** on its own. Your key caps can add up to more than the **Gateway spending cap**, but the organization-wide cap still stops all keys once their combined spend reaches it.
* Key caps reset at the same moment as the **Gateway spending cap**: 00:00 UTC on the 1st of each month. A key's first period runs from when it was created until the next 1st.
* Every key tracks its spend for the month, even without a cap. Adding, changing, or removing a key cap keeps the key's spend so far this month and its reset date.
* If you add a cap below what the key has already spent this month, its requests are refused right away. The key list shows a key's spend only once it has a cap.

### How the key list shows cap usage

Keys with a cap show an extra line under their name on the **Keys** tab:

| Text on the key row | What it means |
| - | - |
| **Key cap: €4.12 of €25.00 used** · **resets Dec 1, 2026** | The key's model costs this month and the date its cap resets. |
| **Key cap reached: €25.00 of €25.00** | The key has used up its cap. Its requests are refused until the cap resets or you raise or remove it. |
| **Key cap €25.00** | The cap is set, but the key's current spend isn't shown. This is normal while a key is **Pending** or **Revoking**. For an active key, its spend couldn't be loaded. Click **Refresh** to try again. |
| ... · **limited by the gateway cap** | The key cap is higher than your current **Gateway spending cap**, for example after you lowered it. The organization-wide cap stops requests first. |

Lowering the **Gateway spending cap** doesn't change existing key caps. Keys whose cap is now higher than the organization-wide cap show **limited by the gateway cap** until you adjust one of the two caps.

## How the two caps work together

DeepMask checks both caps on every request. Whichever cap is reached first blocks the request.

* When a key reaches its own cap, only that key is refused. Your other keys keep working.
* When your keys together reach the **Gateway spending cap**, every key is refused, including keys that still have room under their own cap.

For example, suppose your **Gateway spending cap** is €200 and your staging key has a €25 key cap. Once the staging key has spent €25, only its requests are refused. Once all your keys together have spent €200, requests from every key are refused until the 1st or until you raise the **Gateway spending cap**.

## What a blocked request looks like

When a cap blocks a request, the API returns HTTP `400` or `429` with the standard DeepMask error body. The `code` field tells you which cap was reached:

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

| Code | Cause | What to do |
| - | - | - |
| `API_SPENDING_CAP` | Your organization reached its **Gateway spending cap**. | Ask an organization admin to raise the **Gateway spending cap** on the **Billing** tab, or wait for the reset at 00:00 UTC on the 1st. |
| `API_KEY_SPENDING_CAP` | This key reached its own key spending cap. | Ask an organization admin to raise or remove the key's cap with **Edit spending cap**, or wait for the reset. Other keys are not affected. |

Check `error.code`, not only the HTTP status, because invalid requests also return `400` and rate limits also return `429`. The message text is the same for every error. With `stream: true`, a cap refusal arrives as this JSON error before any stream starts.

The examples below tell the two cap refusals apart. The cURL example prints the HTTP status after the response body. 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, APIStatusError

client = OpenAI(
    api_key=os.environ["DEEPMASK_API_KEY"],
    base_url="https://api.deepmask.io/v1",
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}],
    )
    print(response.choices[0].message.content)
except APIStatusError as error:
    if error.code == "API_KEY_SPENDING_CAP":
        print("This key reached its own spending cap.")
    elif error.code == "API_SPENDING_CAP":
        print("Your organization reached its Gateway spending cap.")
    else:
        raise
```

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

const client = new OpenAI({
  apiKey: process.env.DEEPMASK_API_KEY,
  baseURL: "https://api.deepmask.io/v1",
});

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 && error.code === "API_KEY_SPENDING_CAP") {
    console.log("This key reached its own spending cap.");
  } else if (error instanceof OpenAI.APIError && error.code === "API_SPENDING_CAP") {
    console.log("Your organization reached its Gateway spending cap.");
  } else {
    throw error;
  }
}
```

> [!TIP]
>
> A cap refusal keeps failing until the cap resets or an admin changes it, so don't retry it. If it arrives as `429`, the OpenAI SDKs retry it automatically, twice by default, before they raise the error. Check `error.code` in your error handling and don't retry a cap code yourself. See [Retries in the OpenAI SDKs](https://documentation.deepmask.io/api/errors.md#retries-in-the-openai-sdks).

Blocked requests also appear in the **Request log** on the **Usage** tab with the status **Blocked: gateway cap** or **Blocked: key cap**. See [Usage and logs](https://documentation.deepmask.io/api/usage-and-logs.md).

### Are blocked requests billed?

No. A cap refuses the request before any model runs, so nothing is charged. Blocked requests don't count toward the billed requests on the **Usage** tab.

Requests that were already running when a cap was reached finish normally and are billed. That is why spend can end slightly above the cap.

## Troubleshooting

**Requests are refused with `API_SPENDING_CAP` sooner than you expected?** The cap counts every key in your organization combined. **Monthly API charges** can also lag behind the cap. Requests that are still being priced or checked aren't in it yet, and the page doesn't refresh by itself, so click **Refresh** for the latest figures. Just after 00:00 UTC on the 1st, requests can still be refused for a few minutes until the reset takes effect. Check the **Request log** for **Blocked: gateway cap** entries, then raise the cap on the **Billing** tab or wait for the reset.

**Only one app stopped working?** Check that key's row on the **Keys** tab. If it shows **Key cap reached**, raise or remove the key's cap.

**You can't save a key cap?** The key cap is probably higher than your **Gateway spending cap**. Raise the **Gateway spending cap** first, or choose a lower key cap.

**You need a cap above the maximum?** The **Maximum cap** shown under the field is the highest **Gateway spending cap** you can set yourself. To raise it for your organization, [contact support](https://documentation.deepmask.io/support/contact.md).

**Edit spending cap is unavailable?** The key is still being set up (**Pending**) or is being revoked (**Revoking**). See [API keys](https://documentation.deepmask.io/api/keys.md) for what each key status means.

**Requests are refused with a `429` error?** Check `error.code`. A `429` with `API_SPENDING_CAP` or `API_KEY_SPENDING_CAP` means a spending cap was reached. Any other `429` code comes from a rate, token, or concurrency limit, or from a model's capacity limit. See [429: rate and capacity limits](https://documentation.deepmask.io/api/errors.md#429-rate-and-capacity-limits) for what each code means, and [Limits and fair use](https://documentation.deepmask.io/api/limits.md) for each limit's value.

## Related pages

> [card] [API keys](https://documentation.deepmask.io/api/keys.md)
>
> Create keys, choose their models, and set a cap when you create them.

> [card] [Usage and logs](https://documentation.deepmask.io/api/usage-and-logs.md)
>
> Track monthly charges and find blocked requests in the request log.

> [card] [Billing](https://documentation.deepmask.io/api/billing.md)
>
> Enable API billing and understand what your monthly invoice includes.

> [card] [Errors and retries](https://documentation.deepmask.io/api/errors.md)
>
> Handle error codes and learn which errors to retry.

> [card] [Limits and fair use](https://documentation.deepmask.io/api/limits.md)
>
> See every rate, token, and budget limit in one place.


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