Error structure

json

{
  "error": {
    "code": "validation_failed",
    "message": "The request contains invalid fields.",
    "details": [
      {
        "field": "type",
        "code": "invalid_value",
        "message": "Must be one of: company, private."
      }
    ]
  }
}

code is stable for your code. message is for humans and may change. details appears on validation errors per field. Optionally request_id is included.

HTTP status codes

Status	Meaning
200	OK
201	Created
204	Deleted or success with no body (e.g. product delete)
401	Missing or invalid API key
403	Key missing required scope or module access
404	Object missing or not in your environment
409	Conflict (e.g. actor or module precondition)
422	Validation failed, bad Content-Type or invalid JSON
429	Too many requests — see Rate limits
500	Server error. Try again later

Error codes

Common codes:

Code	Meaning
`validation_failed`	Validation failed; see `details` per field
`invalid_content_type`	Content-Type is not `application/json` where required
`not_found` / `*_not_found`	Resource not found
`rate_limited`	Rate limit exceeded (`429`)
`actor_required`	Conflict: actor required
`online_payments_disabled`	Conflict: online payments disabled
`incasso_disabled`	Conflict: incasso disabled
`mandate_already_verified`	Conflict: mandate already verified

How to handle errors

Branch on error.code, never on message.
On 422, show details to your user — that is what they are for.
On 500 or timeout: retry with the same Idempotency-Key.