Error Handling

All errors share a consistent shape:

{
  "error": {
    "code": "invalid_request",
    "message": "Field 'value' must be a number.",
    "field": "value",
    "request_id": "req_01HZX3Y4Z5"
  }
}

Include the request_id when contacting support — it lets us look up the exact request server-side.

Error codes

Code	HTTP status	Retryable
invalid_request	400
unauthorized	401
forbidden	403
not_found	404
conflict	409
rate_limited	429
internal_error	500
service_unavailable	503

Validation errors

When multiple fields fail validation, error.details lists each one:

{
  "error": {
    "code": "invalid_request",
    "message": "Validation failed.",
    "details": [
      { "field": "name", "message": "must not be empty" },
      { "field": "value", "message": "must be a number" }
    ]
  }
}

Tip

Validate payloads against the API Reference before sending — most invalid_request errors are caught early this way.