Error handling

Errors use this envelope:

{
  "error": {
    "code": "validation_error",
    "message": "A human-readable explanation",
    "details": {},
    "requestId": "..."
  }
}

code is one of unauthorized, forbidden, not_found, validation_error, conflict, or internal_error. Preserve requestId when contacting support.

Status	Meaning	Integration action
400 / 422	Invalid request	Correct the payload using the current catalog or endpoint requirements.
401	Missing or invalid API key	Check the key and environment; do not retry unchanged credentials.
403	Resource belongs to another tenant	Treat as an authorization failure.
404	Resource does not exist for your tenant	Check the identifier; do not create a duplicate merely because a read failed.
409	State or idempotency conflict	Reuse the original payload/key to recover, or fetch the resource.
5xx	Temporary service failure	Retry conservatively with the same idempotency key for creates.