Bill Payments Error handling

For error response format and general handling, see Key concepts.

Bill payment failures can occur in different phases.


Error codes

internalStatusHTTPPhaseDescription
INVALID_PARAMS400AnyInvalid or missing request fields
NO_FUNDS400ExecutionInsufficient balance to cover payment
BILL_AMOUNT400LockBill requires an amount but none was provided
BILL_AMOUNT_OUT_OF_BOUNDS400LockAmount is outside the biller's accepted range
BILL_LOCK_NF404ExecutionBill lock not found — lock may have expired
PAYER_BLOCKED400LockPayer is blocked due to compliance restrictions
MERCHANT_BLOCKED400LockMerchant is blocked due to compliance restrictions
BILL_PAYMENT_STATUS409ExecutionInvalid status transition — operation already terminal

Do not retry on 409. A BILL_PAYMENT_STATUS error 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 companyCode or 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_NF to 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[].errors on the BILL_PAYMENT stage of the synthetic, in the SYNTHETIC_STATUS_UPDATE webhook and in GET /v2/synthetics/{syntheticAnyId}. This is the one to read if you follow payments by webhook, since it arrives without an extra call.
  • cancellationReason on the bill payment, via GET /v2/bill-payments/{externalId}.
  • error.message on 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.

CodeMeaningRecommended action
L1The bill service encountered an unexpected errorStart a new payment flow; contact support if the error persists
L2A bill payment parameter is invalidCorrect the identified field and start a new payment flow
L3A required bill payment parameter is missingSupply the identified field and start a new payment flow
L4The payment amount is outside the allowed rangeRediscover the bill or its limits and use an accepted amount
L5The bill ID was not foundRediscover the bill and create a new lock
L6The bill amount type is invalidRediscover the bill and use its current amount rules
L7The bill payment method is invalidRediscover the bill and select a supported method
L8The bill has expiredRediscover the outstanding bill before starting a new payment
L9The bill has already been paid or processedDo not pay again; verify the existing payment with the biller
L10There are insufficient funds to complete the paymentFund the account, create a new lock, and start a new payment
L11A payment with the same external ID was already processedDo not submit a duplicate; retrieve and reconcile the existing payment
L12The payment could not be processedStart a new payment flow; contact support if repeated attempts fail
L13The bill company rejected the bill service credentialsContact support
L14The bill company encountered an unexpected errorRetry later with a new payment flow; contact support if the error persists
L15The bill company service is unavailableRetry later with a new payment flow
L16The bill or bill company is temporarily unavailableRetry later with a new payment flow
L17The bill company is inactiveDo not retry until the bill company is available again
L18The bill reference is not eligible for this paymentVerify the reference and rediscover the bill
L19An active subscription prevents the paymentRetry only during the final 24 hours of the subscription
L20The maximum number of payment attempts was exceededDo not retry immediately; contact the biller or support
L21A payment for the same bill reference completed recentlyDo not pay again; reconcile the recent payment
L22The bill reference does not belong to the selected companyVerify the company and reference, then rediscover the bill
L23The bill company configuration is invalidContact support
L24The bill service request is invalidRediscover the bill and rebuild the payment request
L25Bill service authorization is invalidContact support
L26Bill service authorization has expiredRetry later with a new payment flow; contact support if the error persists
L27The bill company was not foundRediscover the company before starting a new payment
L28The bill image is invalidCapture or upload a valid bill image and start a new flow
L29The bill image exceeds the maximum allowed sizeReduce the image size and start a new flow
L30The payment amount is below the minimum allowed amountUse at least the biller's minimum amount
L31A required bill parameter does not existCorrect the identified field and rediscover the bill
L32There is no pending billConfirm the reference; do not retry until a new bill is pending
L33The bill reference was not foundVerify the reference and rediscover the bill
L34The bill service credentials are invalidContact support
L35The bill payment is still processingDo not create a duplicate; wait and verify the payment status
L36The bill payment was not foundVerify 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

PhaseAction
DiscoveryFix input (companyCode, referenceId) and retry
Lock expiredRecreate lock — do not reuse expired lock code
Insufficient fundsTop up balance and retry with a new lock
Transient provider failureRetry after delay — check synthetic status first
Terminal (409)Do not retry — start a new payment flow

Did this page help you?