Errors & Rate Limits

The Reinx API uses conventional HTTP status codes and a flat, machine-readable error body.

Error format

Every API error returns a stable code plus a human-readable message:

{ "error": "RATE_LIMITED", "message": "Too many requests.", "retry_after_seconds": 12 }

Some errors add route-specific scalar fields (like retry_after_seconds above) — there is never a nested details object. Branch on the error code, not the message text; messages can change. Casing convention: routes authenticated with a session or organization key return UPPER_SNAKE codes (UNAUTHORIZED, PLAN_LIMIT_REACHED). Routes authenticated with an agent API key return lower_snake codes (unauthorized, agent_disabled, scope_denied).

Request validation failures are the one exception to the shape above — they return Fastify’s standard 400 body, where the machine code lives in code:

{
  "statusCode": 400,
  "code": "FST_ERR_VALIDATION",
  "error": "Bad Request",
  "message": "body/name must NOT have fewer than 1 characters"
}

Common error codes

Status	Code	Meaning
400	`FST_ERR_VALIDATION`	Request body/query failed schema validation (see note above)
400	`BAD_CURSOR` / `INVALID_CURSOR`	Pagination cursor is malformed or expired — restart from the first page
401	`UNAUTHORIZED`	Missing, invalid, revoked, or expired session token OR organization API key — the two share this uppercase code and an identical response shape (see the Organization API key codes below)
401	`unauthorized`	Agent API key is missing, malformed, unknown, or revoked
402	`INSUFFICIENT_BALANCE`	Not enough treasury balance for the requested operation
403	`NO_ORG_SELECTED`	Session has no active organization
403	`INSUFFICIENT_ROLE` / `OWNER_REQUIRED` / `OUT_OF_SCOPE`	Your role or project/team scope doesn’t permit this action
403	`STEP_UP_REQUIRED`	Sensitive action needs fresh re-verification (passkey/TOTP); re-verify and retry with a fresh token
403	`KYC_REQUIRED`	Financial operations are locked until verification completes (`kyb_status` field included)
403	`PLAN_LIMIT_REACHED`	Plan capacity hit — includes `resource`, `limit`, `current`, `plan_tier`, `upgrade_url`
403	`FEATURE_NOT_AVAILABLE`	Feature not on your plan — includes `feature`, `required_tier`, `upgrade_url`
403	`agent_disabled`	The agent is paused or archived — its key still authenticates, but actions are blocked
403	`scope_denied`	The agent key lacks the required tool scope — includes `required_scope`
404	`ORG_NOT_FOUND` (and similar)	The referenced resource doesn’t exist or isn’t visible to you
409	`IDEMPOTENCY_CONFLICT` / `IDEMPOTENCY_KEY_REUSE`	An idempotency key was reused with a different payload — mint a new key for a new logical request
409	`REQUEST_IN_PROGRESS`	The same idempotent request is still executing — wait and re-poll rather than resubmitting
409	`AGENT_ARCHIVED`	The target agent is archived (terminal state)
429	`RATE_LIMITED`	Too many requests. A delay field (`retry_after_seconds` and/or a `retry-after` header) is present on most but not all sources — see the 429 matrix. Detect from the `429` status, not from a delay field
500	`INTERNAL`	Something failed on our side — the message is generic by design; retry with backoff, and contact support if it persists

Organization API key codes

Codes involved in the organization-key lifecycle. Most are returned on routes authenticated with a reinx_org_live_… key; the mint-time codes are returned to a human dashboard session creating or rotating a key, since key management has no machine scope at all. See Authentication for scopes and bindings.

Status	Code	Meaning
400	`IDEMPOTENCY_KEY_REQUIRED`	A machine create was sent without `idempotencyKey`. It is mandatory for keys (not for humans) — generate one and retry
400	`EMPTY_SCOPES`	Mint-time, human session only — `scopes` was sent as an empty array. Send at least one, or omit the field entirely for the default read-only set
400	`INVALID_SCOPE`	Mint-time, human session only — a requested scope is not grantable. Some scopes exist in the vocabulary but cannot be granted to a key; the message lists the grantable set
400	`INVALID_BINDING`	Mint-time, human session only — the binding is malformed in shape: a `scopeId` on an organization-wide key, or a missing `scopeId` on a project/team key. Nothing was looked up. (An unrecognised `scopeType` never reaches this — schema validation rejects it first, as a generic `400` with a `FST_ERR_VALIDATION` code)
400	`BINDING_TARGET_NOT_FOUND`	Human session, on mint OR rotate — the shape was fine but the target isn’t usable: it does not exist, belongs to another organization, or is archived (possibly raced after rotate’s pre-read). Rotate clients must handle this, not just mint
401	`UNAUTHORIZED`	The key itself is missing, malformed, unknown, or revoked — one identical `401` shape for all of them (the reason is deliberately not leaked). This is the normal bad-key response on both transports. A closed org is different, and splits by transport: for an otherwise-valid key, REST returns `403 ORG_CLOSED` (see below), while MCP collapses that state into this same `401`. Also note a `401` from a session-only route (one no key may use) looks the same yet says nothing about the key — so verify a suspect key against a management endpoint before concluding it’s bad
403	`INSUFFICIENT_SCOPE`	The key lacks the required scope — includes `required_scope`. Scopes are fixed at mint; mint a new key
403	`BINDING_NOT_ALLOWED`	The key’s binding rung cannot call this route at all. Most often: trying to edit its own container’s envelope, which lives one rung up
403	`OUT_OF_SCOPE`	The rung may call the route, but the target is outside the key’s container (e.g. a project-bound key reading another project’s agent). Some routes hide it as a `404` instead
403	`ORG_CLOSED`	The organization is terminally closed. Not retryable
403	`MACHINE_ARCHIVE_DENIED`	Terminal evidence-gate failure on `archive_agent` — this key may not archive this agent. Ask a human
409	`VERSION_CONFLICT`	Stale `version` on the AGENT budget-policy PATCH. Re-read, re-apply, retry — never blind-write
409	`STALE_BUDGET`	Stale `version` on a project/team budget PUT. Same recovery — note this is NOT `VERSION_CONFLICT`
409	`STALE_APPROVAL_RULES`	Stale `version` on a project/team approval-rules PUT. Same recovery
409	`KEY_STILL_DELIVERABLE`	Archive refused: the agent’s one-time key window is still open. Replay the create with the same `idempotencyKey` to recover it and keep the agent
409	`KEY_DELIVERY_UNPROVEN`	Archive refused. First confirm from YOUR OWN records that no credential was ever stored for this create — the server cannot tell a lost response from a delivered-but-unused key. Only then replay the create (stamping the expiry) and re-issue the archive. The stamp is best-effort, so if the code recurs, retry the replay + archive with bounded backoff — a persistent recurrence is a proof-stamp fault to escalate, not to loop on. Skipping the records check can destroy a usable agent
409	`BALANCE_UNVERIFIABLE`	Balance couldn’t be confirmed zero. Retryable — try later
409	`ORG_NOT_READY`	Organization provisioning is still in flight. Retry the same `idempotencyKey`
429	`CREATE_QUOTA_EXHAUSTED`	The key’s daily creation quota is spent. Resets at 00:00 UTC — waiting out a rate-limit window will not clear it
503	`QUOTA_UNAVAILABLE`	The quota store is unreachable, so the fail-closed counter denied rather than admitted. Retry the same `idempotencyKey`
503	`CREATE_RETRYABLE`	Agent-create saga contention — not the quota, and never emitted by project/team creates. Retry the same `idempotencyKey`
503	`ORG_KEYS_UNAVAILABLE`	Organization-key auth is not configured in this environment
409	`CREATE_ATTEMPT_EXPIRED`	A stalled agent-create aged out (>30 min) and will not complete. Recovery differs from the transient codes above: start over with a FRESH `idempotencyKey` — replaying the same key keeps returning this
409	`CREATE_ATTEMPT_LOST`	The create attempt’s reservation was rolled back or swept — terminal. Same-key replays return this forever. Start over with a FRESH `idempotencyKey` (do not loop)
500	`ATTEMPT_CORRUPT`	The agent exists but its stored replay body is unreadable. Do NOT re-create with a fresh key (that mints a duplicate) — confirm the agent via `GET /v1/agents` and contact support
5xx	`PROVISIONING_FAILED` / `CREATE_FAILED` / `UPSTREAM_UNAVAILABLE` / `PROVIDER_UNKNOWN`	Coded, persisted terminal create failures — a same-key replay returns the same code forever. Despite the 5xx, these are not transient: recover with a FRESH `idempotencyKey` (for a genuinely new agent). Confirm with exactly one same-key replay first — a rare unpersisted terminal resumes instead
500	`SIGNING_PIPELINE`	A platform-side signing bug — never retry (same key or fresh). Contact support

Rate limits

Limits are applied per organization and scale with plan tier:

Plan	REST API	MCP tools
Free	100 req/min	60 req/min
Pro	1,000 req/min	600 req/min
Enterprise	5,000 req/min	3,000 req/min

Several tighter limits are enforced on top of that org-wide ceiling:

Limit	Applies to
Per-route caps	Sensitive routes — e.g. `POST /v1/agents` at 10/min per organization, and withdrawals
Management-write caps	MCP management-band writes — 20/min per key, 40/min per organization
Daily creation quota	Organization keys creating agents/projects/teams — see below

Authenticated responses carry usage headers:

Header	Meaning
`x-ratelimit-limit`	Requests allowed in the current window
`x-ratelimit-remaining`	Requests left in the window
`x-ratelimit-reset`	Seconds until the window resets

On a REST success these headers describe the general per-organization bucket. On a 429 they describe the tripped bucket only when the per-organization limiter is what rejected you (the org bucket or a scoped per-route cap). For CREATE_QUOTA_EXHAUSTED and the upstream-provider relay, a different mechanism rejected the request while the org limiter passed — so its pre-handler already stamped healthy general-bucket headers that say nothing about the actual rejection. A healthy-looking x-ratelimit-remaining therefore does not rule out a per-route cap or the creation quota, and for those two cases you must not read a delay from the headers at all. Branch on the error code to tell them apart: RATE_LIMITED is a rate limit; CREATE_QUOTA_EXHAUSTED is not.MCP differs: a gateway-level 429 carries no retry_after_seconds (use the retry-after header), its x-ratelimit-reset is a Unix epoch, and a pre-auth IP-level 429 carries no x-ratelimit-* at all. A management tool proxying a REST cap does return retry_after_seconds. Full comparison on Authentication.

Daily creation quota (organization keys)

Distinct from rate limiting: a per-key counter covering agent, project, and team creation (default 100/day) that resets at 00:00 UTC, not on a rolling window. Exhaustion returns 429 CREATE_QUOTA_EXHAUSTED with no retry-after header and no retry_after_seconds — there is no short window to wait out, and backing off will not clear it before the reset. Retrying the same idempotency key + payload within the same UTC day is never re-charged (complete or not); only a cross-midnight resume of an incomplete create costs another unit. Rotating the key does not reset the count.

Handling 429s

First check the code — two 429s are daily lockouts, not throttles. CREATE_QUOTA_EXHAUSTED (organization keys, resource creation) and COPILOT_BUDGET_EXCEEDED (POST /v1/copilotkit, the org’s daily assistant-usage ceiling) both carry no delay and clear only at 00:00 UTC — retrying either on a backoff loop just burns the day. Every other 429 (incl. COPILOT_BUSY, a genuine short throttle) is a short throttle.
For a throttle, wait at least retry_after_seconds (or the retry-after header) before retrying — don’t hammer. When neither is present — the upstream-provider relay case in the 429 matrix carries no delay field at all — fall back to client-side exponential backoff (start ~1s, grow it). Retrying immediately just re-hits the upstream limit.
For write requests, retry with the same idempotency key: the retry is deduplicated and will never double-spend. See the payment workflow for how idempotency keys behave.
If you’re consistently hitting limits at legitimate volume, contact support about your plan’s limits.

Getting Started

Concepts

MCP Tools

Orchestrators

API Reference

Support

Errors & Rate Limits

Error format

Common error codes

Organization API key codes

Rate limits

Daily creation quota (organization keys)

Handling 429s

​Error format

​Common error codes

​Organization API key codes

​Rate limits

​Daily creation quota (organization keys)

​Handling 429s

Error format

Common error codes

Organization API key codes

Rate limits

Daily creation quota (organization keys)

Handling 429s