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

error values
missing_key401No Authorization header. Send the key as a bearer token.
invalid_key401The key is unknown or has been revoked. Ask the account holder for a new one.
rate_limited429Too many calls in the last minute. Wait the number of seconds in Retry-After.
bad_request400A query parameter is wrong. The message names it, for example range: Invalid option.
not_found404No such order on this account, or no proxy account attached yet.
upstream_unavailable503The proxy network did not answer in time. Retry after a moment; Retry-After is set when known.
server_error500Something 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.