Search Overlay

Hosted Errors

JSON error responses from the Hosted API include information in the body of the response similar to the following:

"message":"Invalid currency"
"message":"Not authorised"

The error object consists of the following elements:

Element Type Description Required?
code string The error code. Yes
message string The error message describing the error. Also shown in the X-Application-Error response header. Yes

To save you having to parse the response body to find the error information, you can retrieve the error message from the X-Application-Error response header.

This is a summary of all errors that could be returned when using the Hosted 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.

Hosted Payment Errors

HTTP Status Code Description
400 "Cannot update transaction" You are attempting to update a transaction that cannot be updated. E.g., you are attempting to update a rebill for which the dueDate has passed.
400 "Duplicate merchant reference" You are attempting a transaction using a merchantRefNum that has already been used.
402 "Duplicate merchantCustomerId - Existing profile id XXXX" You are attempting to create a profile using a merchantCustomerId that has already been used.
400 "You submitted an expired credit card number with your request. Please verify this parameter and retry the request." The cardExpiryYear and cardExpiryMonth parameters indicate that the card has expired.
400 "Invalid Id" You have provided an invalid ID with your request.
400 "Invalid profileId" A profile could not be loaded for the profileId provided.
401 "Not authorized" You have provided an invalid API key with your request.
400 "Authorization denied" The authorization was denied because both a payment token and a credit card number were submitted with the request.
400 "Amount exceeds refundable amount" You are attempting to refund an amount that is greater than the original transaction amount (minus the sum of any existing refunds against the transaction).
400 "Request validation failed: currency_code invalid: ' ' is not a valid ISO 4217 currency code" You have provided an invalid currencyCode parameter with your request.
400 "Request validation failed: merchant_ref_num invalid: required field" You have provided an invalid merchantRefNum parameter with your request.
400 "Request validation failed: total_amount invalid: required field" or "Request validation failed: total_amount invalid : '10.00' not an integer" You have provided an invalid totalAmount parameter with your request.
400 "Resend callback failed" Your attempt to resend a callback failed.
402 "Time for completing payment has expired" You are attempting to complete a payment for which the orderTimeout period has expired.
531 "Transaction already processed" You are attempting to make a second payment against a completed order.
400 "Transaction not yet processed" You are attempting to refund is a transaction that has not been processed.