> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PrimerClientError

`PrimerClientError` is the type of errors returned by the SDK. Each error is described by an error code and description it may include contextual information.

## Not all failures are retryable

Before prompting the user to retry after an error, keep two things in mind:

**A client-side error doesn't always mean the payment failed.** An error like `PAYMENT_FAILED` or `PRIMER_SERVER_ERROR` can be caused by conditions local to the browser — for example, a network drop after the payment was submitted. In that case the payment may have completed successfully even though the SDK reported a failure. Your server — through [payment webhooks](https://primer.io/docs/get-started/payment-updates.md) or the Payments API — is the source of truth for the payment's status. Verify the status server-side before asking the user to pay again, otherwise you risk charging them twice.

**Decline reasons are intentionally generic.** When a payment is declined, `PAYMENT_FAILED` doesn't carry the specific decline reason. This is deliberate to avoid leaking details. The detailed reason is available to you server-side via [webhooks](https://primer.io/docs/api-reference/get-started/configure-webhooks.md), the Payments API, and the Primer Dashboard.

### Deciding whether to retry

`PrimerClientError` doesn't say whether the failure happened in transit, so use the presence of `payment` data in `onCheckoutFail` instead. A failure **without** `payment` may be network-caused — a payment may still have been created, so ask your backend before retrying. A failure **with** `payment` identifies the failed payment: cross-check its status and decline reason by `payment.id` before deciding whether to offer a retry.

```javascript theme={"dark"}
onCheckoutFail(error, { payment }, handler) {
  if (!payment) {
    // No payment data — the failure may be network-level and a payment
    // may still have been created. Check with your backend (which listens
    // to Primer webhooks) before letting the user pay again.
  } else {
    // `payment.id` identifies the failed payment. Cross-check its status
    // and decline reason with your backend before offering a retry.
  }

  if (!handler) {
    return;
  }
  return handler.showErrorMessage();
}
```

## Properties

**Properties**

**code** `string`

An error code that matches one in the table below.

**description** `string`

A brief description of the error.

**data** `object`

A field containing contextual data related to the error.

**diagnosticsId** `string`

A unique ID for the error instance, used internally by the SDK.

## Error Codes, Descriptions and Recovery Suggestions

| Error Code | Description | Recovery Suggestion |
| - | - | - |
| `NO_PAYMENT_METHODS` | Indicates that no payment methods were found while attempting to make a&#xA;payment. This can occur for a number of reasons: <li>No payment methods were found in the client session and/or the SDK is&#xA;not initialized.</li>&#xA;<li>`allowedPaymentMethods` filtered out all the payment methods.</li> | <li>Make sure that the payment methods are properly configured on your&#xA;Dashboard, and that at least one payment method can be displayed with&#xA;the data provided in the client session.</li>&#xA;<li>Make sure that&#xA;`allowedPaymentMethods` does not disallow all your supported payment&#xA;methods.</li> |
| `PRIMER_TEARDOWN` | This error indicates that the SDK instance has been torn down and cleaned&#xA;up. It means that checkout UI is removed from the DOM. UniversalCheckout&#xA;instance is also torn down, which will raise an error if any operation that&#xA;requires the UI is attempted. | N/A |
| `PRIMER_SERVER_ERROR` | Indicate one of the following issues when using Apple Pay or PayPal:&#xA;<li>Failed to create Apple Pay session</li>&#xA;<li>An error occurred when vaulting PayPal</li> | Check the description for HTTP error information. |
| `THREE_DS_AUTH_FAILED` | Happens when ThreeDS authentication failed. | Check the error description for details. |
| `TOKENIZATION_ERROR` | Indicates that tokenization was not possible for a card or APM payment,&#xA;or for a vaulted token. For new tokens, this frequently occurs due to issues validating the&#xA;provided data from which the token is created. For vaulted tokens this can occur if a payment method token cannot be&#xA;created from the vaulted token. | Check the error message returned during tokenization. |
| `DUPLICATE_PAYMENT_METHOD_ERROR` | Indicates that the payment method is already vaulted. | |
| `CARD_NUMBER_ERROR` | Indicates the provided card number is invalid. | Display a validation error to the user. |
| `RESUME_ERROR` | Indicates that the merchant cancelled the payment. | N/A - merchant initiated. |
| `VALIDATION_ERROR` | Indicates one of the following:&#xA;<li>Bank issuer is not valid.</li>&#xA;<li>Payment category is not valid (for example, when using Klarna payment&#xA;method).</li> | Display a validation error to the user. |
| `PAYMENT_FAILED` | Payment failed after tokenization. | Check the error for details on what went wrong. |
| `PAYMENT_CREATION_ABORTED` | Payment creation was aborted prior to completion, either by `onBeforePaymentCreate` or because the client session uses `approvalMode: "MANUAL"`. | For `MANUAL` sessions, use [Primer Checkout](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/manual-payment-approval.md) or create the session without `approvalMode: "MANUAL"`. Otherwise N/A - merchant initiated. |
| `PAYMENT_CREATION_DISABLED` | The payment could not be created because payment creation has been&#xA;disabled. | Call `universalCheckout.setPaymentCreationEnabled(true)` to&#xA;reenable it |
| `CLIENT_SESSION_UPDATE_ERROR` | Failed to update the client session details. | |
| `INVALID_ARGUMENT` | Invalid information was passed when initialising SDK. | Check the error for which argument(s) need updating. |
| `VAULT_FETCH` | Indicates a failure to fetch vaulted payment methods. | Check network connection and client session. |
| `VAULT_DELETE` | Indicates failure to delete a vaulted payment method. | Check that the method hasn't already been deleted. |
| `HEADLESS_VAULT_MANAGER_VALIDATION` | Indicates that the provided identifier does not match any vaulted payment&#xA;method. This can occur during payment and when deleting a vaulted payment&#xA;method. | Check that the method exists in the vault. |
| `CARD_FORM_VALIDATION_UNEXPECTED_FIELD` | The field was not defined for the payment method. | Removed the field and re-submit the payment. |
| `MISSING_FIRST_NAME_OR_LAST_NAME` | For Apple Pay, indicates a missing name field. | The user must provide both names in their Apple wallet. |
| `IDEMPOTENCY_KEY_ALREADY_EXISTS` | A payment with the provided idempotency key already exists. | Use a unique idempotency key for each payment request. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.