Bill Payments Error handling
For error response format and general handling, see Key concepts.
Bill payment failures can occur in different phases.
Error codes
internalStatus | HTTP | Phase | Description |
|---|---|---|---|
INVALID_PARAMS | 400 | Any | Invalid or missing request fields |
NO_FUNDS | 400 | Execution | Insufficient balance to cover payment |
BILL_AMOUNT | 400 | Lock | Bill requires an amount but none was provided |
BILL_AMOUNT_OUT_OF_BOUNDS | 400 | Lock | Amount is outside the biller's accepted range |
BILL_LOCK_NF | 404 | Execution | Bill lock not found — lock may have expired |
PAYER_BLOCKED | 400 | Lock | Payer is blocked due to compliance restrictions |
MERCHANT_BLOCKED | 400 | Lock | Merchant is blocked due to compliance restrictions |
BILL_PAYMENT_STATUS | 409 | Execution | Invalid status transition — operation already terminal |
Do not retry on 409. A
BILL_PAYMENT_STATUSerror means the operation has already reached a terminal state. Retrying the same request will not change the outcome. Start a new payment flow if the user needs to retry.
Discovery errors
- Invalid
companyCodeor method mapping - Invalid
referenceId - No outstanding bill found for the reference
These are validation failures. Fix the input and retry.
Lock errors
- Lock validation failed
- Lock expired (use
BILL_LOCK_NFto detect) - Payer or merchant blocked by compliance (
PAYER_BLOCKED,MERCHANT_BLOCKED)
Locks expire. If the user takes too long to confirm, recreate the lock before executing.
Execution errors
- Insufficient funds (
NO_FUNDS) - Payer or merchant blocked by compliance (
PAYER_BLOCKED,MERCHANT_BLOCKED) - Provider or network transient failure
Payment cancellation codes
Provider rejections happen asynchronously and are not returned as HTTP internalStatus values. The value uses the format L<number>: message and reaches you in three places:
stages[].errorson theBILL_PAYMENTstage of the synthetic, in theSYNTHETIC_STATUS_UPDATEwebhook and inGET /v2/synthetics/{syntheticAnyId}. This is the one to read if you follow payments by webhook, since it arrives without an extra call.cancellationReasonon the bill payment, viaGET /v2/bill-payments/{externalId}.error.messageon the payment's history entry for the cancellation, in that same response.
Match on the stable L<number> prefix rather than the full message. For L2, L3, and L31, the message identifies the affected field and can vary by request.
| Code | Meaning | Recommended action |
|---|---|---|
L1 | The bill service encountered an unexpected error | Start a new payment flow; contact support if the error persists |
L2 | A bill payment parameter is invalid | Correct the identified field and start a new payment flow |
L3 | A required bill payment parameter is missing | Supply the identified field and start a new payment flow |
L4 | The payment amount is outside the allowed range | Rediscover the bill or its limits and use an accepted amount |
L5 | The bill ID was not found | Rediscover the bill and create a new lock |
L6 | The bill amount type is invalid | Rediscover the bill and use its current amount rules |
L7 | The bill payment method is invalid | Rediscover the bill and select a supported method |
L8 | The bill has expired | Rediscover the outstanding bill before starting a new payment |
L9 | The bill has already been paid or processed | Do not pay again; verify the existing payment with the biller |
L10 | There are insufficient funds to complete the payment | Fund the account, create a new lock, and start a new payment |
L11 | A payment with the same external ID was already processed | Do not submit a duplicate; retrieve and reconcile the existing payment |
L12 | The payment could not be processed | Start a new payment flow; contact support if repeated attempts fail |
L13 | The bill company rejected the bill service credentials | Contact support |
L14 | The bill company encountered an unexpected error | Retry later with a new payment flow; contact support if the error persists |
L15 | The bill company service is unavailable | Retry later with a new payment flow |
L16 | The bill or bill company is temporarily unavailable | Retry later with a new payment flow |
L17 | The bill company is inactive | Do not retry until the bill company is available again |
L18 | The bill reference is not eligible for this payment | Verify the reference and rediscover the bill |
L19 | An active subscription prevents the payment | Retry only during the final 24 hours of the subscription |
L20 | The maximum number of payment attempts was exceeded | Do not retry immediately; contact the biller or support |
L21 | A payment for the same bill reference completed recently | Do not pay again; reconcile the recent payment |
L22 | The bill reference does not belong to the selected company | Verify the company and reference, then rediscover the bill |
L23 | The bill company configuration is invalid | Contact support |
L24 | The bill service request is invalid | Rediscover the bill and rebuild the payment request |
L25 | Bill service authorization is invalid | Contact support |
L26 | Bill service authorization has expired | Retry later with a new payment flow; contact support if the error persists |
L27 | The bill company was not found | Rediscover the company before starting a new payment |
L28 | The bill image is invalid | Capture or upload a valid bill image and start a new flow |
L29 | The bill image exceeds the maximum allowed size | Reduce the image size and start a new flow |
L30 | The payment amount is below the minimum allowed amount | Use at least the biller's minimum amount |
L31 | A required bill parameter does not exist | Correct the identified field and rediscover the bill |
L32 | There is no pending bill | Confirm the reference; do not retry until a new bill is pending |
L33 | The bill reference was not found | Verify the reference and rediscover the bill |
L34 | The bill service credentials are invalid | Contact support |
L35 | The bill payment is still processing | Do not create a duplicate; wait and verify the payment status |
L36 | The bill payment was not found | Verify the payment ID; start a new flow only after confirming no payment exists |
All funds are returned automatically when the payment reaches CANCELLED. Do not attempt a manual refund.
Recovery strategy
| Phase | Action |
|---|---|
| Discovery | Fix input (companyCode, referenceId) and retry |
| Lock expired | Recreate lock — do not reuse expired lock code |
| Insufficient funds | Top up balance and retry with a new lock |
| Transient provider failure | Retry after delay — check synthetic status first |
| Terminal (409) | Do not retry — start a new payment flow |
Updated 2 months ago