Handling Error Codes

Every error raised by the component is delivered to your onError handler as a plain object:

{
    code: number,
    message: string,
    additionalInfo?: any
}

additionalInfo carries the underlying cause when available (the original exception, or the response body from the DNA Payments backend), useful for logging and debugging.

Hook it up once and branch on code:

function onError(error) {
    switch (error.code) {
        case 1006:
            // QR countdown expired
            break;
        case 1011:
            // paymentData drift: make sure the values you return from
            // onBeforeProcessPayment match the ones passed at init()
            break;
        default:
            console.error('Alipay+ error:', error);
    }
}

Error code reference

Code	Message	When it fires	Recommended action
`400`	Bad request	The DNA Payments API rejected a malformed request from the component.	Inspect `additionalInfo` and report to DNA Payments support if the issue persists.
`401`	Unauthorized	The access token was rejected by the DNA Payments API (expired, malformed, or scoped incorrectly).	Refresh the token via your backend. See Authentication.
`403`	Forbidden	The token is valid but does not grant access to the requested resource.	Verify the OAuth scopes used to mint the token: see Authentication.
`404`	Not found	The DNA Payments API could not locate the requested resource.	Verify `terminalId` and any other identifiers in `paymentData`.
`500`	Internal server error	The DNA Payments API encountered an internal error.	Retry, then escalate to DNA Payments support if the issue persists.
`1000`	Something went wrong	Catch-all for unexpected runtime failures.	Inspect `additionalInfo` and report to DNA Payments support.
`1001`	Failed to render button	The component could not be mounted into `containerElement`.	Confirm the container element exists in the DOM at the time of `init()` and that it is reachable from the script.
`1002`	Failed to process payment	A non-network failure happened while creating the Alipay+ payment order.	Inspect `additionalInfo` to identify the cause.
`1003`	Failed to process payment (timeout)	The request to create the Alipay+ payment order timed out (network-level timeout).	Check the user's connection and retry.
`1004`	Payment data is missing	`paymentData` was not provided at `init()` and no `onBeforeProcessPayment` hook was defined to supply it.	Provide `paymentData` at `init()`, or define an `onBeforeProcessPayment` that returns it. See paymentData reference.
`1005`	Token is missing	The access token was not provided at `init()` and no `onBeforeProcessPayment` hook was defined to supply it.	Provide a valid `access_token` at `init()`, or return one from `onBeforeProcessPayment`. See Authentication.
`1006`	Payment timeout	The customer did not scan the QR code within `paymentTimeoutInSeconds` (default 900).	Show the customer a friendly "QR code expired" message and offer a retry.
`1007`	Failed to execute onBeforeProcessPayment	Your `onBeforeProcessPayment` callback threw an exception.	Wrap the handler body in `try/catch` and surface a friendly message. The original error is in `additionalInfo`.
`1008`	No result returned from onBeforeProcessPayment	`onBeforeProcessPayment` was the only source of `paymentData` and / or `token` (the missing one was not provided at `init()`), and it returned `undefined` / `null`.	Either provide both `paymentData` and `token` at `init()`, or return what is missing as `{ paymentData, token }` (and optionally `paymentTimeoutInSeconds`) from the handler.
`1009`	paymentData field missing in result from onBeforeProcessPayment	`paymentData` was not provided at `init()` and the handler returned a result without a `paymentData` field.	Provide `paymentData` at `init()`, or include it in the value returned from `onBeforeProcessPayment`.
`1010`	token field missing in result from onBeforeProcessPayment	The access token was not provided at `init()` and the handler returned a result without a `token` field.	Provide `token` at `init()`, or include it in the value returned from `onBeforeProcessPayment`.
`1011`	The payment data provided in the onBeforeProcessPayment event does not match the initial payment data. Mismatched fields: `<list>`	The `paymentData` returned from `onBeforeProcessPayment` differs from the `init()` values on one of the locked fields: `amount`, `currency`, or the delivery address.	Keep `amount`, `currency` and the delivery address identical to the `init()` values. Use `onBeforeProcessPayment` to add server-side fields such as `invoiceId`, not to change the displayed total. If the cart amount can change, re-initialize the component instead.

Notes

Always show the user a friendly message rather than the raw error text. The messages above are intended for developers, not end customers.
1006 is the most common code on Alipay+ because the customer has to open their phone, find the QR scanner in their preferred wallet, scan, and confirm. Make the retry path obvious.

Error code reference​

Notes​

Error code reference

Notes