Errors & rate limits

Error shapes, status codes and rate-limit behaviour.

Error shape

Developer (/v1/*) endpoints return errors in a typed envelope:

{
  "error": {
    "type": "invalid_request_error",
    "message": "payout_address must be a 0x EVM address"
  }
}

Status codes

Status	Meaning	What to do
200	Success	—
400	Invalid request (bad JSON or failed validation)	Fix the request body
401	Missing or invalid API key	Check the Authorization header
404	Resource not found	Verify the id/path
429	Rate limited	Back off and retry
5xx	Server error	Retry with backoff; contact support if it persists

Common error types

• authentication_error — the key is missing, invalid or revoked.
• invalid_request_error — a field failed validation; message names the first problem.

Rate limits

Endpoints are rate-limited per key (and per IP as a floor). A limited request returns 429. Use exponential backoff with jitter, and design writes to be safe to retry — pass a stable reference on payments so a retry doesn’t create a duplicate you can’t recognise.