Limits

This page collects every limit the API enforces, the value, and the error you get when you cross it. Use it when you design a question set or a schema, size an input, or plan how much a batch job can send. All of these are checked per request; none of them is a rate.

There is no request-rate limit. OpenType does not count requests per second or per minute, and no response carries a rate-limit header. A 429 is only ever a period quota refusal.

Requests

Limit	Value	Applies to	When exceeded
Body size	4 MiB (4,194,304 bytes)	`POST /v1/runs`, `POST /v1/router/select`	`413 body_too_large`
Body size	1 MiB (1,048,576 bytes)	every other route	a plain-text 413
`Idempotency-Key`	1 to 255 bytes of printable ASCII	`POST /v1/runs` (required), `POST /v1/router/select` (optional)	`400 invalid_idempotency_key`
`x-request-id`	1 to 128 characters from `A-Z a-z 0-9 . _ -`	every route	not an error: the server mints its own `req_` id instead

An Idempotency-Key is scoped to your organization and never expires: a key used once always refers to the same run.

Runs

These apply to every POST /v1/runs, decision or verdict.

Limit	Value	When exceeded
`max_output_tokens`	required, at least 1	`400 invalid_body`
`deadline_ms`, verdict run	1 to 120,000; default 30,000	not an error: values outside the range are clamped (0 becomes 1, larger values become 120,000). A run that runs out of time answers `504 deadline_exceeded`.
`deadline_ms`, decision run	1 to 150,000; default 30,000 plus 120,000 per 262,144 input tokens	clamped the same way, to 150,000 at most. See Long-context decisions.
`capability_hint`	at most 7 values, no duplicates	`400 invalid_verdict_schema`
Estimated input, verdict run	64,000 tokens	`413 input_too_large`
Spend per request	20,000 micro-USD ($0.02), or less if your organization sets a lower ceiling	`503 budget_exhausted` when the run’s budget cannot cover the call

The input estimate is ceil(prompt bytes / 4) + ceil(contract bytes / 4), where the prompt is system plus messages (or the decision state) and the contract is your schema or question set. Roughly, 4 bytes of JSON count as one token. Each run holds its whole spend ceiling as a reservation until it settles, then is charged what it actually cost. With billing on, a run therefore needs up to 20,000 micros of available credit to start, even when it will cost far less.

Decision runs

Limit	Value	When exceeded
Estimated input, Neon 1.1	262,144 tokens (256k)	`413 input_too_large`
Questions per run	1 to 64	`400 invalid_decision_questions`
Alternatives per question	2 to 20 (`noul` always has 2)	`400 invalid_decision_questions`
Question id	non-empty; no `:`, no line break; unique in the set	`400 invalid_decision_questions`
Alternative names	unique within a question	`400 invalid_decision_questions`
`draws`	1 to 8; default 1	`400 invalid_decision_questions`
`think_tokens`	0 to 4,096; default 0	`400 invalid_decision_questions`
Question set size	32 KiB for `instructions` + `questions` + `draws` + `think_tokens`; `state` is not counted	`400 invalid_decision_questions`
`depends_on` and `ask_if`	must name other questions in the set, with no cycle; every `ask_if` list non-empty and naming answers its target can produce	`400 invalid_decision_questions`
`question_order`	exactly the keys of `questions`	`400 invalid_body`
`model`	`neon-1.1` or `neon-latest`; optional	`400 unknown_model`
Model calls per run	exactly 1

Neon 1.1 reads up to 262,144 tokens of input per decision. Verdict runs keep the 64,000-token ceiling. Keep state to the fields the questions need: a smaller input is cheaper and returns sooner.

Long-context decisions

A decision run can carry up to 262,144 input tokens (256k) in a body of up to 4 MiB. Reading that much takes the model longer, so the deadline of a decision scales with its input:

Input	Default deadline	Typical model time
a few thousand tokens	about 30 s	a few seconds
128k tokens	about 90 s	about 40 s
253k tokens	about 146 s	about 110 s
262,144 tokens	150 s

The default is 30,000 + 120,000 × input_tokens / 262,144 milliseconds, clamped to 150,000. You can send a shorter deadline_ms, or a longer one up to 150,000. Verdict runs keep their own range: default 30,000, at most 120,000. Set your HTTP client timeout to at least 160 seconds, above the longest deadline, so the server rather than your client ends a slow run and you receive the 504 deadline_exceeded with its request_id. The official SDKs default to 170 seconds. A long input is priced like any other, per token: a full 262,144-token read with 16 output tokens costs 11,012 micro-USD, within the 20,000 micro-USD per-run ceiling. See Models and pricing.

Response timing

POST /v1/runs returns a Server-Timing header with the time spent in each phase, in milliseconds:

Server-Timing: admit;dur=3.12, upstream;dur=812.40, gateway;dur=9.85, total;dur=822.25

Phase	Meaning
`admit`	Authentication, validation, quota and credit checks before the run starts.
`upstream`	The model call.
`gateway`	Everything except `upstream`: the service’s own overhead.
`total`	The whole request, as the server saw it.

Compare total with your client’s own measurement to see how much time the network took. The header is on 200 and 202 responses and on most refusals. Two properties are not checked at admission: whether each alternative name is a single token for the model, and whether the set fits the model’s answer template. A set that fails either is refused later with 503 decision_unavailable. See Decision questions.

Verdict schemas

Limit	Value	When exceeded
Schema type	a JSON object	`400 invalid_verdict_schema`
Schema size	32 KiB	`400 invalid_verdict_schema`
Nesting depth	12	`400 invalid_verdict_schema`
Nested subschemas	64	`400 invalid_verdict_schema`
Properties	512	`400 invalid_verdict_schema`
`pattern` length	256 characters	`400 invalid_verdict_schema`
`$ref`	a local pointer starting with `#`, pointing inside the same schema	`400 invalid_verdict_schema`
Refused keywords	`$id`, `id`, `$anchor`, `$dynamicAnchor`, `$dynamicRef`, `$recursiveAnchor`, `$recursiveRef`, and any unrecognised keyword with a structured value	`400 invalid_verdict_schema`
Model attempts	2: one answer plus one repair	`503 verdict_schema_violation`

See Verdict runs.

Lists and reports

Limit	Value	When exceeded
`GET /v1/runs` `limit`	1 to 100; default 20	clamped, not refused
`GET /v1/runs` `offset`	0 or more; default 0	a non-integer is `400 invalid_body`
`GET /v1/usage/ledger` `limit`	1 to 200; default 50	`0` is `400 invalid_parameter`; larger values are clamped to 200
`GET /v1/usage/daily` window	at most 92 days	`400 invalid_parameter`
`GET /v1/billing` transactions	the last 50	fixed
`GET /v1/keys`	every key, no paging

Billing

Limit	Value	When exceeded
Checkout `amount_micros`	5,000,000 to 1,000,000,000 ( $5 to$ 1,000), in whole cents	`400 invalid_amount`
Auto-recharge `amount_micros`	same as checkout	`400 invalid_amount`
Auto-recharge `threshold_micros`	at most 1,000,000,000 ($1,000)	`400 invalid_amount`
Auto-recharge charges	at most one per organization per clock hour

Period quotas

An organization can have two limits per quota period. The period is the current UTC calendar month. GET /v1/quota returns the limits, what the period has consumed, and what remains; a null limit means none is set.

Quota	What is compared	When exceeded
Period spend	the run’s spend ceiling (up to 20,000 micros), not its actual cost, against the spend remaining this period	`429 organization_spend_quota_exhausted`
Period tokens	estimated input tokens plus `max_output_tokens` against the tokens remaining this period	`429 organization_token_quota_exhausted`

Because the spend check uses the ceiling, a run can be refused while the period still has a little room left. Held reservations count against the remaining spend until they settle, so a burst of concurrent runs can hit the quota and then clear as those runs finish. A refused run stores nothing, so the same Idempotency-Key is reusable. A replay of a key that already owns a run is never refused with 429.

curl -sS https://api.opentype.dev/v1/quota \
  -H "Authorization: Bearer $OPENTYPE_API_KEY"

const res = await fetch("https://api.opentype.dev/v1/quota", {
  headers: { Authorization: `Bearer ${process.env.OPENTYPE_API_KEY}` }, // needs usage_read
});
const quota = await res.json();
if (!res.ok) throw new Error(`${quota.error.code} (${quota.error.request_id})`);
console.log("spend left:", quota.remaining_spend_micros ?? "no limit");
console.log("tokens left:", quota.remaining_tokens ?? "no limit");
console.log("period ends:", quota.period.end_at);

import os, requests

res = requests.get(
    "https://api.opentype.dev/v1/quota",
    headers={"Authorization": f"Bearer {os.environ['OPENTYPE_API_KEY']}"},  # needs usage_read
    timeout=30,
)
quota = res.json()
if not res.ok:
    raise RuntimeError(f"{quota['error']['code']} ({quota['error']['request_id']})")
print("spend left:", quota["remaining_spend_micros"] if quota["remaining_spend_micros"] is not None else "no limit")
print("tokens left:", quota["remaining_tokens"] if quota["remaining_tokens"] is not None else "no limit")
print("period ends:", quota["period"]["end_at"])

{
  "organization_id": "org_example",
  "period": {"start_at": "2026-09-01T00:00:00Z", "end_at": "2026-10-01T00:00:00Z"},
  "limits": {
    "period_spend_limit_micros": 2000000,
    "period_token_limit": null,
    "request_spend_ceiling_micros": 20000
  },
  "consumed_tokens": {"input_tokens": 824, "output_tokens": 46, "total_tokens": 870},
  "consumed_spend": {"reserved_micros": 20038, "settled_micros": 38, "unsettled_micros": 20000},
  "remaining_spend_micros": 1979962,
  "remaining_tokens": null
}

A quota refusal names the numbers it compared:

{"error":{"code":"organization_spend_quota_exhausted","message":"the estimated provider spend of 20000 micro-USD exceeds the 1200 micro-USD remaining in this quota period","request_id":"req_7d3f0c1a9b2e4f6a8c0d1e2f3a4b5c6d"}}

See Spend limits and quotas.

When the model service is busy

If the model service behind a run limits OpenType’s traffic, the run fails with 503 provider_rate_limited, not 429. That limit is not on your organization. Retry with exponential backoff and a new Idempotency-Key.

Errors - what each refusal above means and whether to retry.
Spend limits and quotas - plan around period quotas.
Models and pricing - what Neon 1.1 costs per token.
Decision questions - design a question set inside the bounds.
Model Router - selection requests share the 4 MiB body cap.

Overview

Errors

Release notes

Limits

Requests

Runs

Decision runs

Long-context decisions

Response timing

Verdict schemas

Lists and reports

Billing

Period quotas

When the model service is busy

​Requests

​Runs

​Decision runs

​Long-context decisions

​Response timing

​Verdict schemas

​Lists and reports

​Billing

​Period quotas

​When the model service is busy

​Related

Requests

Runs

Decision runs

Long-context decisions

Response timing

Verdict schemas

Lists and reports

Billing

Period quotas

When the model service is busy

Related