Errors & Rate Limits

The API uses standard HTTP status codes. Authentication, scope, and rate-limit failures return a JSON body with an error code and a human-readable message. Validation failures return a message and an errors map instead.

Error response format

{
  "error": "forbidden",
  "message": "This API key does not have the required scope: invoices:write",
  "required_scope": "invoices:write",
  "key_scopes": ["invoices:read", "clients:read"]
}

Validation errors (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "due_date": ["The due date must be after the issue date."]
  }
}

HTTP status codes

Rate limits

Each API key is limited to 120 requests per minute. When exceeded, the API returns 429 with these headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 60

Implement exponential backoff when you receive a 429. The window resets every 60 seconds.

Ping endpoint

Use this to verify your key is valid before making other requests.