Errors & rate limits

Reading balances and how charges settle are covered in the concept pages; this page is the developer reference for error envelopes and rate limits.

Balances & units → Money units
Pricing, settlement & who pays → Pricing & settlement
Owner-funding envelope & caps → Governing spend

Error shapes

The API has multiple error envelopes. Parse the response body and status rather than assuming one wrapper.

Request validation

HTTP 422 for missing fields, invalid names, descriptions outside 10-500 characters, invalid schemas, and other typed request validation failures.

{"detail":[{"type":"missing","loc":["body","name"],"msg":"Field required","input":{}}]}

Business errors

A bare JSON list for most credit, budget, scope, rule, and key-management failures.

[{"msg":"SDK credits exhausted.","error":"SDK_CREDITS_EXHAUSTED","required_credits":1.1,"available_credits":0.998}]

Resource rail errors

A detail object for discover/inspect/estimate/run/poll rail failures.

{"detail":{"error":"TOOL_NOT_FOUND","message":"No tool for slug ..."}}

Agent-key auth errors

A detail object with success: false for invalid, disabled, or expired Agent Key authentication.

{"detail":{"success":false,"error":"Agent API key is disabled","code":"agent_key_disabled"}}

Common codes

Code	HTTP	Meaning
`TOOL_NOT_FOUND`	404	The resource slug does not exist; discover again.
`PARAMS_SCHEMA_INVALID` / `CAP_REQUIRED`	422	Inspect the resource, fix params, or add `maxTotalChargeUsd`.
`SDK_CREDITS_EXHAUSTED`	402	The spendable balance cannot cover the run. When reason is `cap_preflight`, retry once with the returned `max_allowed_cap_credits` as the cap.
`SDK_RESOURCE_DISABLED` / `SDK_RESOURCE_*`	403 / 402	An owner resource Rule blocked the run. Surface to the owner; don't retry.
`agent_key_disabled` / `AGENT_KEY_EXPIRED`	403	The key is disabled, or its unclaimed 14-day window expired.
`RUN_NOT_FOUND`	404	The run does not exist or belongs to another agent.
`INVALID_CURSOR`	422	The discover cursor is malformed; omit cursor to restart from the first page.
`UPSTREAM_THROTTLED` / `UPSTREAM_FAILED`	503 / 502	The upstream provider throttled or failed; retry once after a pause.
`AGENT_KEY_RATE_LIMITED`	429	Wait for `Retry-After` before starting another resource run.

Rate limits

The registration limiter allows 5 requests/minute per client IP. GET /v1/agents/me uses the general agent-read limit of 60 requests/minute.
Public discover, inspect, and estimate calls allow 120 requests/minute per IP.
POST /v1/agents/resources/run/{slug} and MCP run_resource use a 60-second sliding window. The default limit is 60 starts/minute on the free tier and 600 starts/minute on paid tiers.
Both a per-key bucket and a same-size per-agent umbrella bucket are enforced, so minting more keys does not multiply an agent's limit.
Run responses expose X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Reset is a duration in seconds, not a timestamp.
A 429 returns Retry-After and a bare list: [{"msg":"Rate limit exceeded","code":"AGENT_KEY_RATE_LIMITED","limit":N,"window":60,"retry_after":N}].
Authenticated run-status reads are scope-checked but do not use the per-key spend-path limiter. Honor Retry-After on any 429 response.