Errors and limits

Error envelope

{
  "error": {
    "code": "guard",
    "message": "...",
    "retryable": false,
    "param": "max-scan",
    "next": ["..."],
    "retry_after": null
  },
  "_meta": {"api_version": "v1", "request_id": "041643766c574a19"}
}

param names the field at fault. Follow error.next first: it says what to change.

Error codes

Code	HTTP	Meaning	What to do
unknown_field	400	Option not available for this command	Use the options listed in next
invalid_argument	400 / 405 / 422	Bad input count, choice, label list or body; wrong HTTP method (405)	Fix what message names
invalid_address	400	Not a valid address or id for this network, or a Zcash shielded pool where only an address is taken	Check the network and the full address
limit_exceeded	422	Value out of range, too many targets, or answer over 16 MiB	Use the documented ranges; split; lower k or limit
guard	422	The scan would exceed max-scan (a very busy address)	Narrow it; see Busy addresses
not_found	404 / 422	Unknown path, network or command (404); address not covered (422)	Read next; try resolve
deadline	504	Stopped after 60 seconds; the time is charged	Narrow it; never resend unchanged
resource	503	The query hit its memory limit	Narrow it; never resend unchanged
rate_limited	429	Over the request rate	Wait retry_after; batch
throttled	429	More than 2 requests at once	Send one call at a time
busy	503	No free slot within 5 seconds	Wait retry_after
quota_exhausted	429	Your daily budget or daily input limit is used up	Stop; it resets at 00:00 UTC
pool_exhausted	429	Your tier’s shared daily time is used up	Stop; it resets at 00:00 UTC. Need more? Ask for the advanced tier on the API keys page
unauthorized	401	API key missing, unknown, revoked or expired	Send Authorization: Bearer <key>; make or regenerate a key
forbidden	403	The key’s account has no access	Check the API keys page
terms	403	The current terms of use were not accepted by their due date	Accept them on the sign-up page; queries work again within a minute
https_required	403	The request used plain HTTP	Use https://; regenerate the key
internal	500	Server fault; message has the request id	Retry once later; report the id

Retries

• Retry only rate_limited, throttled and busy. Wait the Retry-After header (or retry_after) seconds, and retry at most twice more.
• Never retry unchanged: quota_exhausted, pool_exhausted, deadline, resource, guard, or any validation error.

Limits and budget

Limits per account, by tier (they may change during the beta; meta shows yours):

Limit	General	Advanced
Requests per minute	60	120
Concurrent requests	2	2
Query time per UTC day	30 minutes (1,800,000 ms)	24 hours
Inputs per call (targets, address lists)	100	200
Inputs per UTC day	5,000	no limit
Query time shared by the whole tier per UTC day	12 hours	no pool

New accounts start on the general tier; see Get access to ask for advanced.

• Query time is charged even for runs that fail, time out or are abandoned. Validation refusals cost nothing.
• meta costs a request but no query time, and still answers after the budget is used up. guide costs neither. GET /v1 and GET /v1/health need no key.
• Watch _meta.budget.remaining_ms_today. meta shows your own limits, your tier and what is left of its shared pool (tier_pool_remaining_ms_today).