--- updatedAt: 2025-10-02T17:03:32.000Z agentTools: siteIndex: https://docs.recurly.com/llms.txt projectIndex: https://docs.recurly.com/recurly-subscriptions/llms.txt --- # Errors Central reference for `RecurlyError`—learn the common error codes, when they’re emitted, and how to surface customer-friendly messages. Every recoverable problem in Recurly.js is delivered as a **`RecurlyError`object**.\ Key take-aways: * **Consistent shape** – `name`, `code`, `message`, and (when relevant) `fields` or `cause`. * **Thrown vs. emitted** – fatal issues throw immediately; recoverable issues are delivered to callbacks, `on('error')` listeners, or rejected \_PricingPromise\_s. * **UI best-practice** – use the **`code`** to map to your own human copy; the **`message`** is for developers. *** ## Prerequisites and limitations * Client must have run `recurly.configure()`—otherwise you’ll get a `not-configured` error. * Your error-handling logic should **never** rely on the raw `message`; only the stable `code`. * Tables list the most common codes, but gateways can emit additional provider-specific errors—always implement a safe fallback. # Key details Errors are encapsulated by a `RecurlyError`, which contains a few standard properties to help you diagnose error cases and inform your customers accordingly. Errors will be thrown if the exception will prevent proper execution. If an error can be recovered, it will be passed to the proper error handling event listener, callback, or `PricingPromise` handler for you to inspect. ### Best practices The `message` property contains diagnostic information intended to help you diagnose problems with the form, and we do not recommend displaying its contents to your customers. To provide the best customer experience, we recommend that you provide your own error text to be displayed, based on the error code you receive. ### Error codes #### Configuration | Code | Description | | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | | not-configured | This error appears when you try to perform an operation without first calling `recurly.configure`. | | missing-public-key | When you call `recurly.configure`, you must do so with a `publicKey` property. | | invalid-public-key | Check the `publicKey` to ensure it matches that of your admin app's [API Access section](https://app.recurly.com/go/developer/api_access). | #### Tokenization | Code | Description | | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | validation | A request validation error has occurred. This can indicate many possible issues, and you should check the fields property to determine which `fields` caused the error. | | invalid-parameter | Occurs when a tokenization parameter does not pass our internal validations. Check the `fields` property to determine which fields caused the error. | | api-error | A request to the Recurly API has encountered an issue. This too can indicate many possible issues, and we recommend inspecting the `message` and `fields` properties for more information. | #### Pricing | Code | Description | | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | | not-found | This happens when a nonexistent plan is requested. | | missing-plan | A `Pricing` instance will emit this if a plan has not been specified before trying to set a proeprty that depends on a plan, such as a coupon or addon. | | invalid-addon | Occurs when an addon is added to a `Pricing` instance but is not valid for the instance's selected plan. | | invalid-currency | Similarly, if a currency is requested which is not valid for the selected plan. | | gift-card-currency-mismatch | Occurs when a gift card is redeemed with a currency that doesn't match the instance's configured currency. | #### Apple Pay | Code | Description | Additional Properties | | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ | | apple-pay-init-error | A configuration issue has prevented initialization | `err` the originating `RecurlyError`. | | apple-pay-not-configured | Your site does not have a gateway which supports Apple Pay | | | apple-pay-configuration-invalid | There is an issue with your Apple Pay authentication information. Check your certificate and key values in your gateway configuration. | | | apple-pay-merchant-validation-error | Apple encountered an error validating your merchant credentials | | | apple-pay-payment-failure | An error has occurred during tokenization, preventing the payment authorization | | #### PayPal | Code | Description | | :--------------------- | :------------------------------------------------------------------------------------------------ | | paypal-not-configured | In order to perform a PayPal transaction, your site must be configured to accept PayPal reference | | paypal-canceled | The customer canceled the PayPal agreement flow. | | paypal-error | A generic PayPal error has occurred. Inspect `message` to learn more. | | invalid-routing-number | The bank routing number is not valid | #### 3-D Secure | Code | Description | Additional Properties | | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- | | 3ds-auth-error | 3-D Secure authentication has failed because the customer could not be authenticated. We recommend prompting the user to try a different payment method. | `cause` the originating `Error`. | | 3ds-result-tokenization-error | An error occurred while attempting to tokenize the 3-D Secure authentication result. | `cause` the originating `RecurlyError`. | | 3ds-vendor-load-error | A third-party dependency had an issue loading. Dependencies are utilized when required by your payment gateway. | `vendor` the dependency provider. | | 3ds-auth-determination-error | The authentication method necessary to fulfill 3-D Secure requirements could not be determined | | ### Example RecurlyError object ```js { name: 'validation', code: 'validation', message: 'There was an error validating your request.', fields: [ 'number', 'year' ] } ``` *** # Sibling pages * [Overview](https://docs.recurly.com/recurly-subscriptions/docs/overview-recurlyjs.md) * [Getting started](https://docs.recurly.com/recurly-subscriptions/docs/getting-started.md) * [Customizing Elements](https://docs.recurly.com/recurly-subscriptions/docs/styling-elements.md) * [Getting a token](https://docs.recurly.com/recurly-subscriptions/docs/getting-a-token.md) * [Using a token](https://docs.recurly.com/recurly-subscriptions/docs/using-a-token.md) * [Events](https://docs.recurly.com/recurly-subscriptions/docs/events.md) * [Elements](https://docs.recurly.com/recurly-subscriptions/docs/elements.md) * [Apple Pay](https://docs.recurly.com/recurly-subscriptions/docs/apple-pay.md) * [Google Pay](https://docs.recurly.com/recurly-subscriptions/docs/google-pay-tm.md) * [Bank accounts: US, IBAN, BACS, BECS](https://docs.recurly.com/recurly-subscriptions/docs/bank-accounts-us-iban-bacs-becs.md) * [Adyen APMs: PayPay, Boleto, iDEAL, Sofort, and Cash App](https://docs.recurly.com/recurly-subscriptions/docs/boleto-ideal-sofort-and-cashapp.md) * [PayPal](https://docs.recurly.com/recurly-subscriptions/docs/paypal.md) * [Venmo](https://docs.recurly.com/recurly-subscriptions/docs/venmo.md) * [Amazon Pay](https://docs.recurly.com/recurly-subscriptions/docs/amazon-pay-v2-js.md) * [Pricing](https://docs.recurly.com/recurly-subscriptions/docs/pricing.md) * [3D Secure](https://docs.recurly.com/recurly-subscriptions/docs/3d-secure.md) * [Fraud](https://docs.recurly.com/recurly-subscriptions/docs/fraud.md) * [Recurly Engage](https://docs.recurly.com/recurly-subscriptions/docs/engage.md) * [Validation](https://docs.recurly.com/recurly-subscriptions/docs/validation.md) * [Examples](https://docs.recurly.com/recurly-subscriptions/docs/examples.md) * [React & TypeScript](https://docs.recurly.com/recurly-subscriptions/docs/react-typescript-support.md) * [Upgrading](https://docs.recurly.com/recurly-subscriptions/docs/upgrading.md) * [Support](https://docs.recurly.com/recurly-subscriptions/docs/support.md)