API

Errors and limits

What each error means, which ones to retry, and how many requests you can run at once.

Error format

Errors come back with a status code and a JSON body: a message to show, and a code to act on.

402 · response.json

1{2  "error": "No analyses left this month. Add a credit pack or move to a bigger plan.",3  "code": "no_credits"4}

Codes

Status	Code	Means	Retry?
400	—	The request is wrong: not a Solana address, depth out of range, a missing field.	No, fix it
401	`login`	No key sent.	No
401	`invalid_key`	The key is not valid, or was revoked.	No
402	`no_credits`	Nothing left on your plan or in packs.	After topping up
429	`rate_limited`	Too many requests running at once for your account.	Yes, when one finishes
500	—	The analysis or trace failed.	Yes
503	`busy`	Iris is at capacity.	Yes, after a few seconds
504	`timeout`	The work took too long.	Yes, maybe at a lower depth

Refunds

A request that fails is not charged: errors, timeouts, and analyses that could only return labels (meta.scope database). The x-iris-credits header always shows the balance after the call.

Limits

3 requests at once per account (analyses and traces together). The fourth gets 429.
When Iris is at capacity, a request waits up to 20 seconds for its turn, then gets 503.
Work that takes over 2 minutes stops with 504.

Retrying well

Retry 429, 500, 503 and 504 with a growing delay (2 s, 4 s, 8 s…). Never retry a 400, 401 or 402 as is.