Error Handling

All errors from the Payments API share one structure. Whether an error appears in an error response, on a failed payment, or in a webhook payload, it is the same object:

Error Responses

Requests that fail return an errors array at the top level of the response body.

API error (400)

Returned when request parameters fail contract validation. The data attribute contains per-attribute messages.

{
  "errors": [
    {
      "code": "ZIS01",
      "title": "Bad Request",
      "detail": "The request parameters are invalid.",
      "data": {
        "amount": ["can't be blank"],
        "uid": ["can't be blank"]
      }
    }
  ]
}

Failed Payments

When a payment fails asynchronously, the payment resource in subsequent responses includes an errors array describing the cause.

{
  "data": {
    "status": "failed",
    "errors": [
      {
        "code": "ZIC01",
        "title": "Creditor Account Alias Not Resolved",
        "detail": "The creditor account alias could not be resolved."
      }
    ]
  }
}

A failed payment's payments_payout.finalised webhook carries the same errors array — see the Webhooks page.

Failure Code Prefixes

All codes use the ZI prefix (Zepto payment Initiation). The third character indicates the responsible party:

• S — Shared (applies regardless of side)
• D — Debtor (originator of the payment)
• C — Creditor (recipient of the payment)

Shared Failure Codes

Codes that may apply to any request or payment, regardless of which side caused the issue.

Debtor Failure Codes

Codes indicating the issue originated from the debtor side (e.g. account configuration, available funds).

Creditor Failure Codes

Codes indicating the issue originated from the creditor side (e.g. unable to resolve the destination account).