Follow

WePay API Error Codes

 

Here is a list of WePay API Error codes, and the most common errors over the past 6 months.  If you are receiving an error and need assistance, please email api@wepay.com.

Please also be sure to review our error handling best practices, outlined below.

Error Content

Any error returned via the WePay API will include an error, error description, and error code:

Structure:

{"error":"[type_of_error]", "error_description":"[description_of_error]", "error_code":[code_of_error]}
Example:

{"error":"processing_error","error_description":"Unable to charge payment method: general decline","error_code":1008}

 

  • Error: A basic error category. Most errors are outlined in our general error page, but others include: invalid_parameter (similar to invalid_request) and throttle_exceeded (relating to the rate of API calls from your app).
  • Error Description: A brief description of why the error occurred. You should parse this information and make it available to your internal teams for debugging. Consuming and displaying the Error Description is vital to troubleshooting and resolving errors since Error and Error Code alone can refer to many variations of the same type of error.
  • Error Code: An integer that can be used to aggregate and analyze error trends. It can also be cross referenced on our general error page where you will find a corresponding general description. Please note that this will not always match the Error Description, so it is still important to parse the Error Description.

Interpreting Errors

  • Logging calls: Logging and storing all of your API calls (including those that result in an error) is highly recommended both for maintaining your own data set independent of WePay, and for handling errors.
  • HTTP Errors: For all HTTP response codes other than 2XX, the WePay API Error Code must be parsed out. Additionally, retrying the call will not resolve the issue in most cases, so further investigation of the error code is required. We suggest getting started by visiting our status page, paying special attention to the API component: https://status.wepay.com/#

Please note that HTTP Timeout Errors can be returned to look like an API error, and our status page is still the best place to get started on resolving.

  • Parsing errors: Use the Error Code to guide your programmatic handling and troubleshooting. Key error information is also included in the Error Description portion of an error response, so parse out the Error, Error Description, and the Error Code so that all pieces can be retrieved if needed.
  • Handling errors by type: Errors can result from an issue on WePay’s end, an issue with your app making the call or call formatting, or a change to an object. For errors that result from a change that has been made to an object, you will want to build logic in your code to handle the error, rather than troubleshoot it. For example, error “4003: This payment method can no longer transact” should be handled with a lookup on the payment method and a message to the payer that a new payment method is needed when the lookup returns a deleted, expired, or invalid state.


Common Errors

Below we’ve outlined some of our most common errors along with our recommended action. We’ve also compiled a list our top errors from the past 6 months that you can view here.

1001: Access Token has been revoked

Access tokens become revoked if no KYC/settlement information is provided after disablement or if you issue a new token to the user. This error is common when a new token has been issued but the old one is being used in the API.

Recommended Remediation

If you did not log an accidental token, then you can generate a new token for the user. Build your logic to log and use the new token any time one is generated. That being said, you would want to build logic so that you are not generating a new token when an existing user on your end wants to create another account on your platform.

1008: There was an unknown error - Contact api@wepay.com

This error can occur for various reasons. Commonly, 1008 will return on duplicate attempts that already received a different error. Additionally, 1008 will return when a payment permanently fails or when edge case occur.

Recommended Remediation

Review your API log to determine if this error is returning on retried calls that initially returned a different error with more helpful context to troubleshoot and resolve. If not, then reach out to api@wepay.com If this returns on the /checkout/create endpoint AND you are utilizing unique checkout IDs, retry the payment. If the Error Description returns with “Unique ID failed permanently,” then resubmit with a new unique ID.

NOTE: If you have not leveraged unique IDs for checkouts, please see our notes in our /checkout/create reference:

https://developer.wepay.com/api/api-calls/checkout#create

1008, 2002, 2003, 2004, 2005, 2006, 2007, 2008, or 2009: Unable to charge payment method: general decline

The card issuer declined the payment. Reasons that a card issuer might decline a charge include insufficient funds, card reported as lost/stolen, or general. That being said, the exact reason is not provided to WePay.

Recommended Remediation

Whenever an Error Description includes Unable to charge payment method: general decline, the payer will need to either use a different card or work directly with their card issuer as WePay can only process payments that the card issuer authorizes.

3002, 3302, 4002, 5002, 6002, or 7001: The User with that Access Token cannot access this object

This typically occurs when your app attempts to take action on an object such as a checkout, preapproval, or withdrawal that was initially created with an access token that has since been updated, but the original access token is still being passed to us. the checkout.

Recommended Remediation

To resolve these errors, first examine your logs to confirm that you are sending the same access token that you currently have on file for the user. If you are, then check if any new tokens have been issued to that user that you did not log (/oauth2/token calls would issue a new token).

4003: This payment method can no longer transact

There are many reasons a payment method may not be able to transact. For instance if we attempt to authorize a credit card, but the authorization gets declined, the credit card object will move to an Invalid state.

Recommended Remediation

You should first determine if the card is in a Deleted, Expired, or Invalid state with a lookup call. If so, payer will need to submit a new payment method. Otherwise, please reach out to WePay’s merchant support at:

https://support.wepay.com/hc/en-us/requests/new.

3003: This account has been deleted

Sometimes users will inadvertently delete their WePay account from the merchant dashboard, or your records may not be up to date.

Recommended Remediation

Create a new account or reach out to WePay’s merchant support to re-enable the account.

 

NOTE: IPNs will send you an update as soon as an account is deleted rather than attempting an API call and receiving an error. You can read more about our IPNs here:

https://developer.wepay.com/docs/articles/ipn

1010: You do not have sufficient permissions

Some WePay features require permission from your Account Manager to use. The endpoints that require permission are marked with a green “Permission Required” banner in our API Reference.

Recommended Remediation

If you receive this error while attempting to create CAD or GBP accounts, reach out to api@wepay.com. For any other features, reach out to your Account Manager to determine your eligibility for the feature.

1007: Your app has been throttled for making too many calls. Please retry this call later

WePay will automatically throttle your API calls at 30 calls per 10 seconds in order to protect against attacks and coding errors.

Recommended Remediation

Retry the call later if you’ve experienced a one-off.

If you expect to regularly exceed our throttle limit, we recommend our Batch API:

https://developer.wepay.com/api/api-calls/batch

If you regularly experience this issue after adequately implementing the Batch API, reach out to us and we will work with you to resolve the issue.

Was this article helpful?
2 out of 3 found this helpful
Have more questions? Submit a request

Comments