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 1005:
            // PayPal is disabled on the terminal, confirm with DNA Payments
            break;
        case 1015:
            // PayPal rejected the approval, show the customer a retry path
            break;
        case 1017:
            // paymentData drift, make sure the values you return from
            // onBeforeProcessPayment match the ones passed at init()
            break;
        default:
            console.error('PayPal 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`	PayPal terminal ID is missing	`init()` was called without `terminalId`.	Pass `terminalId` to `init()`.
`1002`	Container element is missing	`init()` was called without `containerElement`, or the element passed was not connected to the DOM at render time.	Ensure the container element exists in the DOM at the time of `init()`.
`1003`	Failed to fetch terminal configuration	The DNA Payments API call that loads the terminal-side PayPal config failed.	Verify `terminalId`, inspect `additionalInfo`.
`1004`	PayPal configuration is missing in terminal configuration	The terminal exists but has no PayPal section configured on the backend.	Enable PayPal on the terminal in the portal at `Settings → Online payment methods → PayPal`. If the error persists after enabling it, contact DNA Payments.
`1005`	PayPal is disabled in terminal configuration	The terminal has a PayPal config but its `status` is not `active`.	Toggle PayPal on for the terminal in the portal at `Settings → Online payment methods → PayPal`.
`1006`	PayPal client ID is missing in terminal configuration	The terminal-side PayPal config exists but has no `clientId`.	Contact DNA Payments: the `clientId` is set on the DNA side.
`1007`	Failed to render PayPal button	Loading the PayPal JS SDK or calling `paypal.Buttons().render()` failed.	Inspect `additionalInfo`. Most often this is a network failure or a CSP rule blocking the PayPal SDK host.
`1008`	Payment data is missing	`paymentData` was not provided at `init()` and was not returned from `onBeforeProcessPayment`.	Provide `paymentData` at `init()`, or return it from `onBeforeProcessPayment`. See paymentData reference.
`1009`	Token is missing	The access token was not provided at `init()` and was not returned from `onBeforeProcessPayment`.	Provide a valid `access_token` at `init()`, or return one from `onBeforeProcessPayment`. See Authentication.
`1010`	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`.
`1011`	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 }` from the handler.
`1012`	Payment data field is 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`.
`1013`	Token field is 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`.
`1014`	Failed to create order	The DNA Payments API call that creates the PayPal order failed.	Inspect `additionalInfo` for the underlying cause. Offer the user a retry.
`1015`	Failed to approve order	PayPal returned a rejection when the order was approved.	Show the user a friendly failure and offer a retry.
`1016`	Unsupported transaction type	The terminal is configured with a transaction type the component cannot use with PayPal.	Contact DNA Payments to align the terminal's transaction type with PayPal.
`1017`	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.
Terminal-configuration codes (1003, 1004, 1005, 1006) are not bugs in your integration. They mean PayPal is not (yet) set up correctly on the terminal side. 1004 / 1005 are self-service: toggle PayPal on for the terminal in Settings → Online payment methods → PayPal. 1003 / 1006 are DNA-side issues, contact DNA Payments.

Error code reference​

Notes​

Error code reference

Notes