All API errors return a JSON envelope with an HTTP status code.
Error response structure
Validation errors (422) include an errors object with per-field messages from Zod:
Branch error-handling logic on HTTP status and message strings. Validation errors should inspect the errors object.
HTTP status codes
Common messages
Authentication
Idempotency
Payment routes
Rate limits
Global: 200 requests per 15 minutes. Auth endpoints: 20 per 15 minutes.
On 429, back off and retry. There is no X-RateLimit-* header today.
Idempotency and retries
When using API keys, mutating requests require Idempotency-Key. Retrying with the same key returns the cached success response — safe for network failures.
Use a new idempotency key for each distinct operation.
Example error handler (JavaScript)