Errors

Every error response — validation failures, domain rule violations, auth rejections — uses the same envelope:

{
  "code": "idempotency.conflict",
  "message": "Idempotency-Key conflict: payload mismatch",
  "request_id": "019f5334-1e22-7082-a665-b54b0e93bfba",
  "correlation_id": "019f5334-1e22-7082-a665-b54b0e93bfba"
}

Field	Description
code	Stable, dot-namespaced machine-readable error code (e.g. validation.request, auth.insufficient_scope, idempotency.conflict). Safe to branch on in your integration.
message	Human-readable description. Can change wording over time — don’t parse it.
request_id	Unique ID for this specific HTTP request. Include it when contacting support about a specific failed call.
correlation_id	Groups related requests together (e.g. a request and the async processing it triggers). Include it for issues spanning more than one request.
params	(optional) Structured detail about the failure — present on some domain errors.
is_transient	(optional) true if retrying the exact same request later may succeed (e.g. a temporary downstream dependency issue) — false/absent means retrying without changing anything will fail the same way.

Common status codes

Status	Meaning
400	Malformed request (bad query parameter, invalid cursor)
401	Missing or invalid authentication
403	Authenticated, but not authorized for this resource or scope
404	Resource not found (or not visible to your organization)
409	Conflict — most commonly an idempotency key reuse with a different payload, or a concurrent update conflict
422	Request body failed validation — see params for field-level detail
5xx	Unexpected server error — check is_transient before retrying