Error Handling | QwikLive API

Error Envelope

All non-2xx responses return a structured error object. Always capture the correlationId and include it in any support request.

json

{
  "success":       false,
  "apiName":       "QwikLive Experience API",
  "version":       "v1",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "timeStamp":     "2026-06-03T14:30:00Z",
  "errorDetails": [
    {
      "code":    400,
      "reason":  "HTTP:BAD_REQUEST",
      "message": "Validation error: transaction.rrn is required."
    }
  ]
}

Field	Type	Description
success	boolean	Always `false` for error responses
apiName	string	API identifier
version	string	API version
correlationId	string	Echoes the `x-correlation-id` request header. Include in all support queries.
timeStamp	string	ISO-8601 timestamp of the error
errorDetails[].code	number	HTTP status code
errorDetails[].reason	string	Machine-readable reason string. Stable across API versions.
errorDetails[].message	string	Human-readable error description

🚨

Important

The errorDetails[].reason field is machine-readable and stable across API versions. Parse this field in your error-handling logic rather than parsing the human-readable message string.

HTTP Status Codes

Code Reason When It Occurs Retryable?

200—Request processed successfully—

400HTTP:BAD_REQUESTMissing required field, schema validation failure, or invalid formatNo

401HTTP:UNAUTHORIZEDClient ID / secret invalid or missingRe-auth

403HTTP:FORBIDDENAuthenticated but not authorized for this operationNo

404HTTP:NOT_FOUNDAccount, institution, or biller not found in coreNo

405HTTP:METHOD_NOT_ALLOWEDWrong HTTP verb used — all service endpoints require POSTNo

406HTTP:NOT_ACCEPTABLEAccept header mismatch — use application/jsonNo

408HTTP:TIMEOUTClient request timed out at API gatewayYes

415HTTP:UNSUPPORTED_MEDIA_TYPEContent-Type is not application/jsonNo

429HTTP:TOO_MANY_REQUESTSRate limit exceeded — back off and retry after Retry-After headerYes

500HTTP:INTERNAL_SERVER_ERRORUnexpected server failureYes

501HTTP:METHOD_NOT_IMPLEMENTEDOperation not available in this versionNo

502HTTP:BAD_GATEWAYGateway returned an invalid upstream response60s

503HTTP:BAD_CONNECTIVITYAPI or upstream system unavailableYes

504HTTP:GATEWAY_TIMEOUTCore banking or upstream did not respond in timeSame RRN

Transaction Response Codes

The status.responseCode field in financial transaction responses carries the core banking response code. A value of "000" indicates a successfully approved and posted transaction. All other values indicate a declined or failed transaction.

ℹ

Note

responseCode values are determined by the connected core banking system and may vary per institution configuration. Always log the full correlationId alongside the responseCode for support tracing.

responseCode	Meaning	Recommended Action
000	Approved	Transaction posted successfully. Return success to the cardholder.
001–099	Declined — various	Specific decline reason varies by core banking system. Log the full responseCode and correlationId.
100	Invalid card	Card not found or invalid. Ask cardholder to use another card.
101	Card expired	Card expiry date has passed. Ask cardholder to use a valid card.
110	Insufficient funds	Account balance below requested amount. Offer a lower amount or alternative account.
120	Exceed daily limit	Requested amount exceeds the account daily transaction limit. Advise cardholder.
200	Do not honour	Generic decline from core. Do not share the reason with the cardholder.
902	Invalid transaction	Transaction type not valid for the account type. Verify `transaction.type` and account.
999	System error	Core banking system error. Retry after a delay. Include `correlationId` in logs and support tickets.

Troubleshooting Guide

400 Bad Request

Check the errorDetails[].message field — it identifies which required field is missing or which validation rule failed. Common causes:

Missing transaction.rrn — must be a 12-digit numeric string
Missing or incorrect transaction.type — must match the endpoint's expected value (e.g., CASHWITHDRAWAL for the debits endpoint)
Missing biller.bin on bill payment requests (required from EAPI v1.0.5)
Sending both profileData fields and neverAsk: true in the same preference upsert request

401 Unauthorized

Verify that both client_id and client_secret headers are present and contain valid credentials for the target environment. Sandbox credentials do not work in production.

404 Not Found

The account ID, institution ID, or biller ID in the request was not found in core banking. Verify using the sandbox test data. In production, check that the institution ID matches the correct environment.

504 Gateway Timeout — Safe to Retry

When you receive a 504, the core banking system did not respond in time. The transaction may or may not have posted. Always retry with the same original RRN — the RRN acts as an idempotency key to prevent duplicate postings.

⚠

Warning — Retry with Original RRN

On 504 retries, do not generate a new RRN. Reuse the original transaction.rrn so the core banking system can detect and reject a duplicate if the original transaction already posted.

429 Too Many Requests

Your integration has exceeded the rate limit. Check the Retry-After response header for the number of seconds to wait before retrying. Implement exponential backoff in your retry logic.

Transaction Declined (responseCode ≠ 000)

A 200 HTTP response with a non-zero status.responseCode means the transaction was received and processed but declined by core banking. Steps:

Log the status.responseCode and correlationId
Map the code using the table above
Do not expose internal decline codes to cardholders — show a generic message instead
For 999 (system error), retry after a brief delay with the same RRN