Card Errors
JSON error responses from the Card Payments API include information in the body of the response similar to the following:
{
"error":{
"code":"5279",
"message":"The authentication credentials are invalid.",
"links":[
{
"rel":"errorinfo",
"href":"https://developer.paysafe.com/en/rest-api/cards/test-and-go-live/card-errors#ErrorCode5279"
}
]
}
}
{
"error":{
"code":"5023",
"message":"You submitted a request that is not parseable.",
"details":[
"Unrecognized token 'fale': was expecting 'null', 'true', 'false' or NaN at [line: 4, column: 26]"
],
"links":[
{
"rel":"errorinfo",
"href":"https://developer.paysafe.com/en/rest-api/cards/test-and-go-live/card-errors/#ErrorCode5023"
}
]
}
}
The error object consists of the following elements:
Element | Type | Description | Required? | |
---|---|---|---|---|
code | string | The error code. Also shown in the X-Application-Status-Code response header. | Yes | |
message | string | The error message describing the error. | Yes | |
details | string array | Details of any parameter value errors in the body of the request. | Optional | |
links | rel | string | The type of link: "errorinfo". | Yes |
href | string | The URL within the Developer Center that contains a description of the error. | Yes |
To save you having to parse the response body to find the error information, you can retrieve the error code from the X-Application-Status-Code response header.
This is a summary of all errors that could be returned when using the Card Payments API, including HTTP Status Codes.
HTTP Status Code Summary
Code Range | Description |
---|---|
1xx: Informational | Communicates transfer protocol–level information. |
2xx: Success | Indicates that the client’s request was accepted. |
3xx: Redirection | Indicates that the client must take some additional action in order to complete the request. |
4xx: Client Error | Indicates that the client has made an error with the request. |
5xx: Server Error | Indicates that an error occurred on the server side. |
Common HTTP Response Status Codes
Code | Description |
---|---|
200 OK | Everything worked as expected. |
201 Created | The request was successful. Paysafe created a new resource and the response body contains the representation. |
202 Accepted | This indicates that the client’s request will be handled asynchronously. It tells the client that the request appears valid, but it still may have problems once it is processed. |
204 No Content | This is usually returned in response to a PUT, POST, or DELETE request when the REST API declines to send back any status message or representation in the body of the response message. |
304 Not Modified | The client's cached version of the representation is still up to date. |
400 Bad Request | This often indicates that a required parameter is missing or that a parameter is invalid. This is a generic client-side error status, used when no other 4xx error code is appropriate. |
401 Unauthorized | This indicates that the client tried to operate on a protected resource without providing the proper authorization. They may have provided the wrong credentials or none at all. |
402 Payment Required | The parameters were valid but the request failed. |
404 Not Found | The requested resource does not exist. |
405 Method Not Allowed | The client tried to POST or PUT to a resource that would not accept it. |
415 Unsupported Media Type | The request is in a format not supported by the requested resource for the requested method. |
429 Too Many Requests | The application is sending too many simultaneous requests. |
500 Internal Server Error | An error occurred with an internal server. |
502 External Server Error | We received an invalid response from the upstream gateway in attempting to fulfill the request. |
Common Errors
HTTP Status Code | Error Code | Description |
---|---|---|
500 | 1000 | An internal error occurred. |
502 | 1001 | An error occurred with the external processing gateway. |
500 | 1002 | An internal error occurred. |
500 | 1003 | An internal error occurred. |
500 | 1007 | An internal error occurred. |
500 | 1008 | An internal error occurred. |
429 | 1200 | The API call has been denied as it has exceeded the permissible call rate limit. |
401 | 5000 | Your merchant account authentication failed. Either your store ID/password is invalid or the IP address from which you are sending the transaction has not been authorized. |
400 | 5001 | The submitted currency code is invalid or your account does not support this currency. |
400 | 5003 | You submitted an invalid amount with your request. |
400 | 5004 | You submitted an invalid account type with your request. |
400 | 5005 | You submitted an invalid operation type with your request. |
400 | 5010 | The submitted country code is invalid. |
400 | 5016 | The merchant account you provided cannot be found. |
400 | 5017 | The merchant account you provided is disabled. |
402 | 5021 | Your transaction request has been declined. |
400 | 5023 | The request is not parsable. |
409 | 5031 | The transaction you have submitted has already been processed. |
401 | 5040 | Your merchant account is not configured for the transaction you attempted. |
400 | 5042 | The merchant reference number is missing or invalid or it exceeds the maximum permissible length. |
400 | 5068 | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. |
404 | 5269 | The ID(s) specified in the URL do not correspond to the values in the system. |
403 | 5270 | The credentials provided with the request do not have permission to access the requested data. |
406 | 5271 | You requested a response in the 'Accept' header that is in an unsupported format. |
406 | 5272 | The 'Content-Type' you specified in request header was submitted in an unsupported format. |
404 | 5273 | Your client reached our application but we were unable to service your request due to an invalid URL. |
401 | 5275 | The authentication credentials provided with the request have expired. |
401 | 5276 | The authentication credentials provided with the request provided have been disabled. |
401 | 5277 | The authentication credentials provided with the request have been locked due to multiple authentication failures. |
401 | 5278 | The authentication credentials provided with the request were not accepted for an unknown reason. |
401 | 5279 | The authentication credentials are invalid. |
401 | 5280 | The required authentication credentials were not provided. |
405 | 5281 | The request uses an action (e.g., GET, POST, or PUT) that is not supported by the resource. |
400 | 5501 | The profile does not have an active credit card. |
400 | 5500 | Either the payment token is invalid or the corresponding profile or bank account is not active. |
Authorization Errors
HTTP Status Code | Error Code | Description |
---|---|---|
400 | 3064 | Your merchant account is not configured for low value exemptions. |
400 | 3065 | Requested amount exceeds the maximum low value exemptions amount. |
400 | 3066 | Low value exemption not allowed for transactions with storedCredential. |
400 | 3067 | When authentication.exemptionIndicator is present do not provide other authentication fields. |
402 | 3007 | Your request has failed the AVS check. Note that the amount has still been reserved on the customer's card and will be released in 3–5 business days. Please ensure the billing address is accurate before retrying the transaction. |
400 | 3008 | You submitted a card type for which the merchant account is not configured. |
402 | 3009 | Your request has been declined by the issuing bank. |
402 | 3011 | Your request has been declined by the issuing bank because the card used is a restricted card. Contact the cardholder's credit card company for further investigation. |
402 | 3012 | Your request has been declined by the issuing bank because the credit card expiry date submitted is invalid. |
402 | 3013 | Your request has been declined by the issuing bank due to problems with the credit card account. |
402 | 3014 | Your request has been declined - the issuing bank has returned an unknown response. Contact the card holder's credit card company for further investigation. |
402 | 3015 | The bank has requested that you process the transaction manually by calling the cardholder's credit card company. |
402 | 3016 | The bank has requested that you retrieve the card from the cardholder – it may be a lost or stolen card. |
402 | 3017 | You submitted an invalid credit card number with your request. |
402 | 3018 | The bank has requested that you retry the transaction. |
402 | 3019 | Your request has failed the CVV check. Please note that the amount may still have been reserved on the customer's card, in which case it will be released in 3–5 business days. |
402 | 3020 | The bank has requested that you retry the transaction. |
404 | 3021 | The confirmation number included in this request could not be found. |
402 | 3022 | The card has been declined due to insufficient funds. |
402 | 3023 | Your request has been declined by the issuing bank due to its proprietary card activity regulations. |
402 | 3024 | Your request has been declined because the issuing bank does not permit the transaction for this card. |
400 | 3025 | The external processing gateway has reported invalid data. |
400 | 3026 | The external processing gateway has reported the account type is invalid. |
402 | 3027 | The external processing gateway has reported a limit has been exceeded. |
502 | 3028 | The external processing gateway has reported a system error. |
402 | 3029 | The external processing gateway has rejected the transaction. |
402 | 3030 | The external processing gateway has reported the transaction is unauthorized. |
400 | 3031 | The confirmation number you submitted with your request references a transaction that is not on hold. |
402 | 3032 | Your request has been declined by the issuing bank or external gateway because the card is probably in one of their negative databases. |
402 | 3035 | Your request has been declined due to exceeded PIN attempts. |
402 | 3036 | Your request has been declined due to an invalid issuer. |
402 | 3037 | Your request has been declined because it is invalid. |
402 | 3038 | Your request has been declined due to customer cancellation. |
402 | 3039 | Your request has been declined due to an invalid authentication value. |
402 | 3040 | Your request has been declined because the request type is not permitted on the card. |
402 | 3041 | Your request has been declined due to a timeout. |
402 | 3042 | Your request has been declined due to a cryptographic error. |
402 | 3044 | You have submitted a duplicate request. |
402 | 3045 | You submitted an invalid date format for this request. |
402 | 3046 | The transaction was declined because the amount was set to zero. |
402 | 3047 | The transaction was declined because the amount exceeds the floor limit. |
402 | 3048 | The transaction was declined because the amount is less than the floor limit. |
402 | 3049 | The bank has requested that you retrieve the card from the cardholder – the credit card has expired. |
402 | 3050 | The bank has requested that you retrieve the card from the cardholder – fraudulent activity is suspected. |
402 | 3051 | The bank has requested that you retrieve the card from the cardholder – contact the acquirer for more information. |
402 | 3052 | The bank has requested that you retrieve the card from the cardholder – the credit card is restricted. |
402 | 3053 | The bank has requested that you retrieve the card from the cardholder – please call the acquirer. |
402 | 3054 | The transaction was declined due to suspected fraud. |
402 | 3055 | This type of transaction is not supported. |
402 | 3056 | The original transaction type does not match. |
402 | 3057 | Please tell cardholder to call the issuer – do not retry transaction. |
402 | 3060 | Your request has been declined because Strong Customer Authentication is required. Prior to authorizing again, all payment authorization requests that return this response must be retried with 3DS2 Authentication or marked as Exempt. This is also referred as a "Soft Decline". For more information on ‘Soft Declines’ and what to do when you receive one, please refer to 3DS2 Additional Information page. |
Void (Authorization Reversal) Errors
HTTP Status Code | Error Code | Description |
---|---|---|
400 | 3500 | The confirmation number included in this request could not be found. |
402 | 3501 | The requested Void (Authorization Reversal) amount exceeds the remaining Authorization amount. |
402 | 3502 | You cannot process an Void (Authorization Reversal) transaction against an Authorization that has been settled. |
402 | 3503 | The Void (Authorization Reversal) transaction is not supported for the card type used for the Authorization you are attempting to reverse. |
402 | 3504 | The external processing gateway for which your merchant account is configured does not support partial Voids (Authorization Reversals). |
500 | 3505 | The Void (Authorization Reversal) could not be completed. |
402 | 3506 | The Void (Authorization Reversal)amount exceeds the remaining amount of the Authorization. |
402 | 3507 | The Authorization does not support a partial Void (Authorization Reversal). |
Settlement Errors
HTTP Status Code | Error Code | Description |
---|---|---|
400 | 3200 | You have submitted an invalidly formatted Authorization ID for this Settlement. |
404 | 3201 | The Authorization ID included in this Settlement request could not be found. |
402 | 3202 | You have exceeded the maximum number of Settlements allowed. |
402 | 3203 | The Authorization is either fully settled or cancelled. |
402 | 3204 | The requested Settlement amount exceeds the remaining Authorization amount. |
402 | 3205 | The Authorization you are attempting to settle has expired. |
402 | 3206 | The external processing gateway has rejected the transaction. |
402 | 3207 | Due to issuer policies, this type of transaction is not allowed |
Refund Errors
HTTP Status Code | Error Code | Description |
---|---|---|
402 | 3402 | The requested Refund amount exceeds the remaining Settlement amount. |
402 | 3403 | You have already processed the maximum number of refunds allowed for this Settlement. |
402 | 3404 | The Settlement has already been fully refunded. |
402 | 3405 | The Settlement you are attempting to Refund has expired. |
402 | 3406 | The Settlement you are attempting to Refund has not been batched yet. There are no settled funds available to Refund. |
400 | 3407 | The Settlement referred to by the transaction response ID you provided cannot be found. |
400 | 3408 | You have submitted an invalidly formatted response ID for the original Purchase or Settlement. |
402 | 3412 | The Refund transaction you attempted was not permitted because your merchant account is in overdraft. |
402 | 3413 | The requested Refund amount exceeds the permissible Visa credit ratio. |
400 | 3414 | The Refund referred to by the transaction response ID you provided cannot be found. |
402 | 3415 | You cannot cancel this transaction as it is no longer in a pending state. |
402 | 3416 | The external processing gateway for which your merchant account is configured does not support partial Settlements. |
402 | 3417 | There is already another request being processed on the transaction referenced for this request. |
402 | 3418 | The external processing gateway for which your merchant account is configured does not support partial Credits. |
402 | 3419 | This type of transaction cannot be refunded. |
500 | 3420 | An error occurred while processing the purchase return authorization. |
402 | 3421 | The purchase return authorization has been declined by the issuing bank. |
402 | 3422 | The purchase return authorization has failed. |
500 | 3423 | An error occurred while processing the purchase return authorization reversal. |
500 | 3424 | Something went wrong with the purchase return authorization, please retry the transaction. |