Errors

Every error is JSON:

{ "error": { "code": "insufficient_credits", "message": "Not enough credits. Nothing was executed and nothing was charged." } }

Match on code. The message is for a human and may be reworded; the code will not change without a version bump.

Status	code	What happened	Charged?
400	invalid_request	Malformed parameter.	No
400	invalid_limit	limit above the maximum for that route.	No
401	missing_key	No Authorization header.	No
401	invalid_key	Not a key we recognise.	No
401	key_revoked	You revoked it.	No
402	insufficient_credits	Not enough credits. Nothing was executed.	No
403	key_suspended	Suspended after repeated refused requests.	No
404	not_found	No such token, collection or presale.	No
429	rate_limited	Too many requests a second.	No
429	too_many_concurrent	Too many requests in flight at once.	No
429	cost_ceiling	This key spent its per-minute credit budget.	No
503	server_busy	We are shedding load.	No
503	service_disabled	The public API is switched off.	No
500	server_error	Our fault.	No

The two that matter

402 insufficient_credits means nothing ran. The check happens before the query, not after it — you have not been charged, and you have not received a partial answer. The body tells you your balance and where to top up.

A 429 sets Retry-After. Honour it. Repeatedly ignoring a 429 will auto-suspend the key for fifteen minutes; we suspend the key rather than banning your IP address, because a ban would take out everyone behind your egress and a browser challenge is not something an API client can solve.

What we never do to a valid key

We do not IP-ban you and we do not serve you a browser challenge. If you hold a valid key, the worst outcome is a 429 or a temporary suspension of that key.