Error Handling | QwikLive Digital API

The Error Envelope

Non-2xx responses share one shape, so your integration can handle errors uniformly:

ExperienceErrorResponse

{
  "code": "BAD_REQUEST",
  "message": "transaction.ref is required.",
  "status": 400,
  "correlationId": "7c3e1b90-2a44-4c8e-9b1a-0f5d2a6e8c10"
}

💡

Branch on code, not message

The code field is stable and machine-readable; message is human-facing and may change. Always log the correlationId for support.

Status	Code	When it happens
`400`	`BAD_REQUEST`	Validation failed — a required field is missing or malformed.
`401`	`UNAUTHORIZED`	Missing or invalid client credentials.
`403`	`FORBIDDEN`	Credentials valid but not permitted for this operation.
`404`	`NOT_FOUND`	The referenced account, user, institution, or resource does not exist.
`409`	`CONFLICT`	The request conflicts with the current state (e.g. duplicate or already-processed).
`422`	`UNPROCESSABLE_ENTITY`	The request was well-formed but could not be processed as-is.
`500`	`INTERNAL_ERROR`	Unexpected server error.

4xx — do not retry blindly; fix the request or credentials first. 409 usually means the operation already happened — verify before retrying.
500 — transient; retry with exponential backoff and a fresh X-Correlation-Id.
For transactional operations, use a unique transaction.ref so retries are not double-processed.