Errors and limits
Every failure is JSON with a stable code you can switch on and a message you can show. Success is a 200 with the resource itself.
Shape
A failed call has a non-2xx status and a body with two fields. error is fixed and safe to compare; message is for humans and may change wording.
429 Too Many Requests
{
"error": "rate_limited",
"message": "Over 120 requests a minute for this key. Slow down."
}Codes
missing_key401 | No Authorization header. Send the key as a bearer token. |
invalid_key401 | The key is unknown or has been revoked. Ask the account holder for a new one. |
rate_limited429 | Too many calls in the last minute. Wait the number of seconds in Retry-After. |
bad_request400 | A query parameter is wrong. The message names it, for example range: Invalid option. |
not_found404 | No such order on this account, or no proxy account attached yet. |
upstream_unavailable503 | The proxy network did not answer in time. Retry after a moment; Retry-After is set when known. |
server_error500 | Something failed on our side. It is logged; retry later or write to support. |
Rate limits
Each key may make 120 requests a minute, across all endpoints. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; the first refused call answers 429 with Retry-After in seconds. Calls without a valid key share a much smaller allowance per address, so guessing keys is slow by design.
Polling advice
Balances move when traffic flows, not faster. Polling plans once a minute is plenty for a dashboard; once every few minutes is plenty for an alert.