Errors

Every error returns the same JSON envelope, with an HTTP status that matches the type:

{
  "error": {
    "type": "validation_error",
    "code": "validation_error",
    "message": "One or more fields are invalid",
    "requestId": "b3f1…",
    "details": { "fieldErrors": { "customerId": ["Required"] } }
  }
}

• type — a coarse machine category (below).
• code — a stable slug you can branch on.
• message — a human-readable sentence.
• requestId — include this when contacting support.
• details — optional structured context (e.g. field-level validation errors).

Status codes

Status	type	When
400	invalid_request	Malformed request, bad params, missing Idempotency-Key
401	authentication_error	Missing, invalid, revoked or expired key
403	permission_error	The key lacks the required scope
403	tenant_suspended	The account is suspended
404	not_found	No such resource in your company
409	conflict	Idempotency-Key reused with a different request
422	validation_error	Well-formed but semantically invalid input
429	rate_limited	Too many requests — see Retry-After
500	internal_error	Something went wrong on our side

Request ids

Every response carries an X-Request-Id header (echoed in error bodies as requestId). Log it — it's the fastest way for us to trace a request.