Hosted Errors
JSON error responses from the Hosted API include information in the body of the response similar to the following:
"error":{
"code":"400",
"message":"Invalid currency"
}
{
"error":{
"code":401,
"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. |