Spend limits

Use spend alerts to track monthly API costs. To stop traffic after tracked spend reaches a configured amount, enforce a hard spend limit for your organization or an individual project.

Hard spend limits can interrupt production traffic. When tracked spend reaches an applicable hard limit, affected API requests return a 429 error with the insufficient_quota code. Enforcement is not instantaneous, so recorded spend can slightly exceed the configured amount.

Choose a spend control

Spend alerts and hard spend limits have different effects:

Control	What happens at the configured amount	Use it when you want to
Spend alert	Sends a notification; API traffic continues	Track spend without interrupting traffic
Hard spend limit	Affected API requests return a `429` error	Enforce a monthly organization or project cap

Spend alerts do not enforce a cap. They remain active when you add a hard spend limit, so you can use alerts for notification before a hard limit interrupts traffic.

OpenAI also assigns your organization an approved monthly usage limit based on its usage tier. This OpenAI-approved usage limit is separate from the spend limits you configure.

Configure a spend limit

You need permission to manage the applicable organization or project settings. For details, see API Platform permissions.

Go to Organization limits.
In Spend, select Edit spend limit.
Enter the Monthly spend limit.
To make API responses fail after the organization reaches the limit, turn on Enforce a hard limit.
Select Save.

Understand hard-limit behavior

Organization and project hard limits can both apply to a request:

An organization hard limit applies to API traffic across all projects in the organization.
A project hard limit applies only to API traffic billed to that project.
Reaching either applicable hard limit causes affected requests to return 429 errors with the insufficient_quota code.
Raising or removing the reached limit allows traffic to resume after the update propagates. Otherwise, the limit resets with the next monthly cycle.

Enforcement is not instantaneous. The API Platform can process a small amount of extra usage while the limit state propagates, so recorded spend can slightly exceed the configured amount.

Spend alerts

Use spend alerts to get notified before spend reaches a hard limit. Add alerts at thresholds that allow time to adjust usage, raise the limit, or investigate unexpected traffic.

Restore API traffic

If requests return quota-related 429 errors:

Compare current usage with the organization and project spend limits that apply to the request.
Raise or remove the reached hard limit if traffic should resume before the monthly reset.
If tracked spend is below every applicable hard limit, check whether the organization exhausted prepaid credits or reached its OpenAI-approved usage limit.
If the error reports a request or token rate limit instead of insufficient_quota, follow the rate limit guide.

guides/spend-limits.md +35 −12

1# Spend limits1# Spend limits

2 2

3Spend limits help you control API costs by setting monthly budgets for your organization or for individual projects. You can use them as a soft budget for monitoring spend, or enforce a hard limit so API responses fail after spend reaches the limit.3Use spend alerts to track monthly API costs. To stop traffic after tracked spend reaches a configured amount, enforce a hard spend limit for your organization or an individual project.

4 4

~~5## How spend limits work~~5Hard spend limits can interrupt production traffic. When tracked spend reaches

6 an applicable hard limit, affected API requests return a `429` error with the

7 `insufficient_quota` code. Enforcement is not instantaneous, so recorded spend

8 can slightly exceed the configured amount.

6 9

~~7Spend limits are monthly limits measured in U.S. dollars. They can apply at two levels:~~10## Choose a spend control

8 11

~~9- **Organization spend limits** apply across the organization.~~12Spend alerts and hard spend limits have different effects:

~~10- **Project spend limits** apply to a single project.~~

11 13

~~12You can also enforce either level as a hard limit, which makes API responses fail after spend reaches the monthly limit.~~14| Control | What happens at the configured amount | Use it when you want to |

15| ---------------- | ------------------------------------------- | --------------------------------------------- |

16| Spend alert | Sends a notification; API traffic continues | Track spend without interrupting traffic |

17| Hard spend limit | Affected API requests return a `429` error | Enforce a monthly organization or project cap |

13 18

~~14## Using hard limits~~19Spend alerts do not enforce a cap. They remain active when you add a hard spend limit, so you can use alerts for notification before a hard limit interrupts traffic.

15 20

16A hard limit causes API responses to fail after the organization or project reaches its monthly spend limit. After spend reaches a hard limit, API responses return a `429` error until you increase the spend limit or the limit resets.21OpenAI also assigns your organization an approved monthly [usage limit based on its usage tier](https://developers.openai.com/api/docs/guides/rate-limits#usage-tiers). This OpenAI-approved usage limit is separate from the spend limits you configure.

17 22

~~18Use hard limits when you need to prevent unexpected spend, such as for experiments, development projects, or customer-specific projects with fixed budgets.~~23## Configure a spend limit

19 24

~~20## Configuring spend limits~~25You need permission to manage the applicable organization or project settings. For details, see [API Platform permissions](https://developers.openai.com/api/docs/guides/rbac).

21 26

22 27

23 28

45 50

46 51

47 52

53## Understand hard-limit behavior

55Organization and project hard limits can both apply to a request:

57- An organization hard limit applies to API traffic across all projects in the organization.

58- A project hard limit applies only to API traffic billed to that project.

59- Reaching either applicable hard limit causes affected requests to return `429` errors with the `insufficient_quota` code.

60- Raising or removing the reached limit allows traffic to resume after the update propagates. Otherwise, the limit resets with the next monthly cycle.

62Enforcement is not instantaneous. The API Platform can process a small amount of extra usage while the limit state propagates, so recorded spend can slightly exceed the configured amount.

48## Spend alerts64## Spend alerts

49 65

50Use spend alerts to get notified before spend reaches the monthly limit. Add alerts at thresholds that give your team enough time to adjust usage, increase the limit, or investigate unexpected traffic.66Use spend alerts to get notified before spend reaches a hard limit. Add alerts at thresholds that allow time to adjust usage, raise the limit, or investigate unexpected traffic.

68## Restore API traffic

70If requests return quota-related `429` errors:

51 71

52For broader usage analysis, review the [usage dashboard](https://platform.openai.com/settings/organization/usage). For request-rate constraints, see the [rate limits guide](https://developers.openai.com/api/docs/guides/rate-limits).721. Compare [current usage](https://platform.openai.com/settings/organization/usage) with the organization and project spend limits that apply to the request.

732. Raise or remove the reached hard limit if traffic should resume before the monthly reset.

743. If tracked spend is below every applicable hard limit, check whether the organization exhausted prepaid credits or reached its OpenAI-approved usage limit.

754. If the error reports a request or token rate limit instead of `insufficient_quota`, follow the [rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits).