organization_token_quota_exhausted

organization_token_quota_exhausted means your organization’s token limit for the current period has too few tokens left for this run. Read this page when runs fail with a 429 and the code names tokens.

HTTP	`code`	Retryable
`429`	`organization_token_quota_exhausted`	Yes, once the request is smaller or the period has room. Keep the same `Idempotency-Key`.

What happened

Route: POST /v1/runs. An organization can have a token limit per quota period. The period is the current UTC calendar month. Before each run, OpenType estimates the tokens the run could use and compares that with the tokens left:

run estimate     = input estimate + max_output_tokens
input estimate   = ceil(prompt bytes / 4) + ceil(contract bytes / 4)
tokens remaining = period token limit - tokens used this period

If the run estimate is larger than the tokens remaining, the run is refused. max_output_tokens counts in full, even when the answer turns out shorter. The run was refused before it existed. Nothing was stored and nothing was charged. A replay of an Idempotency-Key that already owns a run is never refused with 429. The message gives both numbers:

the estimated <n> tokens exceed the <m> tokens remaining in this quota period

A 429 from OpenType always means a period quota refused the run. The response does not say when to retry, so choose your own backoff.

How to fix

Read the quota with GET /v1/quota (needs usage_read). remaining_tokens is what is left in the period.
Lower max_output_tokens to what the answer needs. A decision run usually needs very few output tokens; the example in the quickstart uses 16.
Shrink the input: trim the state or prompt, and shorten the questions or schema.
If the period is used up, wait for the next period, which starts at 00:00:00Z on the first day of the next month.
Retry with the same Idempotency-Key. The refused request never created a run, so the key is still free, even after you lower max_output_tokens or trim the input.

Example

{"error":{"code":"organization_token_quota_exhausted","message":"the estimated 9000 tokens exceed the 4000 tokens remaining in this quota period","request_id":"req_7d3f0c1a9b2e4f6a8c0d1e2f3a4b5c6d"}}

Checking the tokens left before sending a run:

curl -s https://api.opentype.dev/v1/quota \
  -H "Authorization: Bearer $OPENTYPE_API_KEY" \
  | jq '{period, limit: .limits.period_token_limit, remaining: .remaining_tokens}'

const inputEstimate = 420;   // ceil(prompt bytes / 4) + ceil(contract bytes / 4)
const maxOutputTokens = 16;

const res = await fetch("https://api.opentype.dev/v1/quota", {
  headers: { Authorization: `Bearer ${process.env.OPENTYPE_API_KEY}` },
});
const quota = await res.json();
if (!res.ok) throw new Error(`${quota.error.code}: ${quota.error.message}`);

const remaining = quota.remaining_tokens; // null means no token limit
if (remaining !== null && inputEstimate + maxOutputTokens > remaining) {
  console.warn(`token quota: ${remaining} left, this run needs ${inputEstimate + maxOutputTokens}; resets ${quota.period.end_at}`);
}

import os
import requests

input_estimate = 420  # ceil(prompt bytes / 4) + ceil(contract bytes / 4)
max_output_tokens = 16

resp = requests.get(
    "https://api.opentype.dev/v1/quota",
    headers={"Authorization": f"Bearer {os.environ['OPENTYPE_API_KEY']}"},
    timeout=30,
)
quota = resp.json()
if not resp.ok:
    raise RuntimeError(f"{quota['error']['code']}: {quota['error']['message']}")

remaining = quota["remaining_tokens"]  # None means no token limit
if remaining is not None and input_estimate + max_output_tokens > remaining:
    print(
        f"token quota: {remaining} left, this run needs {input_estimate + max_output_tokens}; "
        f"resets {quota['period']['end_at']}"
    )

Spend limits and quotas - period limits and GET /v1/quota.
organization_spend_quota_exhausted - the spend side of the same period quota.
input_too_large - how the input estimate is computed and capped.
Problem codes - every code, its status, and whether a retry can help.

Overview

Errors

Limits

Release notes

organization_token_quota_exhausted

What happened

How to fix

Example

​What happened

​How to fix

​Example

​Related

What happened

How to fix

Example

Related