Search Overlay

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
(Array of rel:href pairs)

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.