On this page
No Headings
Last updated: June 3, 2026
Important: PayPal Provisioning Platform is a limited-release solution available only to select partners at this time. For more information, reach out to your PayPal Account Manager.
PayPal generally handles most errors internally. In some situations, PayPal
might return the user to the merchant's redirect_uri with an
error_description and error parameters. This table describes the
possible errors:
| Error | Error description | Description | Recommendation |
|---|---|---|---|
RESTRICTED_ACCOUNT | Not applicable | Possible issue with user account. For assistance, user must contact PayPal. | Notify the user that a problem occurred linking their account. For assistance, user must contact PayPal. |
COUNTRY_NOT_SUPPORTED | Not applicable | This product is not available in your country. | Contact PayPal for assistance. |
REFERRAL_EXPIRED | Not applicable | User clicked or was directed to a link that took more than 15 minutes to open. | Relaunch the flow by starting with the referral ID creation. |
SESSION_TIMEOUT | Not applicable | Too much time spent trying to complete the process or the PayPal configuration was not set up correctly. |
If timeout happens during testing, escalate the error to your PayPal account manager.
If this error occurs only once in live PayPal, relaunch the linking flow from the beginning of card selection/referral ID creation.
If you repeatedly run into issues after going live, escalate to your PayPal account manager.
| | CREATE_ACCOUNT_ERROR | Not applicable | PayPal might be experiencing
site issues |
| | INTERNAL_SERVER_ERROR | Not applicable | PayPal might be experiencing
site issues |
| | ACCESS_DENIED| Consent denied | User clicked the **Not Now** option on
the PayPal consent screen. | Notify the user to click **Agree** on the final
consent screen to complete the linking flow. Then, prompt the user to restart
the process. |
| Status code and name | Methods | Details |
|---|---|---|
400 Bad Request VALIDATION_ERROR | ||
POST /v1/payment-networks/linked-instruments | Invalid data provided. Identifies any kind of input error. | |
401 Unauthorized | ||
POST v1/payment-networks/linked-instruments | Invalid access token used. | |
403 Forbidden NOT_AUTHORIZED | ||
POST /v1/payment-networks/linked-instruments | Authorization failed due to insufficient permissions. | |
422 Unprocessable Entity | ||
| ||
500 Internal Server Error INTERNAL_ERROR | ||
POST /v1/payment-networks/linked-instruments | An internal server error has occurred. Internal server error. |