Rate limits & errors

Generous defaults, clear headers, predictable errors.

Rate limits

Standard

600 requests/minute per API key, burst 100. Webhook deliveries don't count against your quota.

Headers

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset so you can back off gracefully.

Higher tiers

Need more? Enterprise plans raise the ceiling — talk to sales.

Error codes

400invalid_paramA parameter is malformed

401unauthorizedMissing or invalid API key

403forbiddenKey lacks permission (same as its owner)

404not_foundResource does not exist

409conflictIllegal state transition

422validation_failedBusiness validation failed (see details[])

429rate_limitedToo many requests — back off

500internal_errorSomething broke on our side

422 example

422 Unprocessable Entity
{
  "error": "validation_failed",
  "message": "qty must be positive",
  "details": [{ "field": "lines[0].qty", "issue": "must be > 0" }]
}

Versioning

All endpoints live under /v1. Breaking changes ship as a new major version (/v2) with at least 12 months of overlap. Additive changes (new fields, new endpoints) never break you.