Customer Vault Errors
JSON error responses from the Customer Vault API include information in the body of the response similar to the following:
"error":{
"code":"5068",
"message":"Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected.",
"fieldErrors":[
{
"field":"locale",
"error":"Invalid Locale"
}
],
"links":[
{
"rel":"errorinfo",
"href":"https://developer.paysafe.com/en/rest-api/vault/test-and-go-live/vault-errors/#ErrorCode5068"
}
]
}
"error":{
"code":"7505",
"message":"The merchantCustomerId provided for this profile has already been used for another profile - 2e7daaac-49f1-4aae-befb-e9b03a30cbc8",
"links":[
{
"rel":"errorinfo",
"href":"https://developer.paysafe.com/en/rest-api/vault/test-and-go-live/vault-errors/#ErrorCode7505"
}
]
},
"links":[
{
"rel":"existing_entity",
"href":"https://api.test.paysafe.com/customervault/v1/profiles/2e7daaac-49f1-4aae-befb-e9b03a30cbc8"
}
]
{
"error": {
"code": "7521",
"message": "The merchantCustomerId provided is used in the following number of profiles: 2",
"links": [
{
"rel": "errorinfo",
"href": "https://developer.paysafe.com/en/rest-api/vault/test-and-go-live/vault-errors/#ErrorCode7521"
}
]
},
"links": [
{
"rel": "existing_entity",
"href": "http://localhost:8412/customervault/v1/profiles/656c3c63-978e-42bc-ab86-e589ad246138"
},
{
"rel": "existing_entity",
"href": "http://localhost:8412/customervault/v1/profiles/0c4bd194-415d-44f0-b2be-9fa521cf0185"
}
]
}
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-Status-Code response header. | Yes | |
| fieldErrors (Array of field:error pairs) | field | string | If there is an error in a field, the identity of the field. | Optional |
| error | string | The error in the field. | 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 | |
If you specify an attribute unique to an existing profile, there is also a separate links object - an array of rel:href pairs - with the following elements:
| Element | Type | Description | Required? |
|---|---|---|---|
| rel | string | The text "existing_entity" | Yes |
| href | string | The URL to use to look up the existing profile. | 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 Customer Vault 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. |
Customer Vault Errors
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 409 | 7503 | The card number you are trying to add to this profile is already used by this profile. |
| 409 | 7504 | This card has been used for the maximum number of profiles allowed. Please use a different card. |
| 409 | 7505 | The merchantCustomerId provided for this profile has already been used for another profile. |
| 409 | 7506 | The bank account you are trying to add to this profile is already in use. |
| 409 | 7507 | The mandate reference you are trying to add to this profile is already in use. |
| 400 | 7508 | You submitted an invalid card number or brand or combination of card number and brand with your request. |
| 409 | 7509 | The bank account has one or more existing Mandates so associated banking information cannot be updated. |
| 400 | 7510 | You submitted invalid bank account information for your banking scheme. |
| 404 | 7511 | The address ID provided in your request could not be found. |
| 400 | 7512 | The merchant's Apple Pay configuration could not be found. |
| 400 | 7513 | The Apple Pay token is invalid. |
| 404 | 7514 | The payment token has expired. |
| 409 | 7515 | The card cannot be added to this profile because the profile has reached the maximum number of cards allowed. |
| 400 | 7516 | You need to provide at least one search parameter. |
| 400 | 7517 | You need to provide dates with the format YYYY-MM-DDTHH24:MI:SSZ. |
| 400 | 7518 | The days between the dates specified exceeds the maximum. |
| 400 | 7519 | The pagination limit exceeds the maximum. |
| 409 | 7520 | The bank account cannot be added to this profile because the profile has reached the maximum number of bank accounts allowed. |
| 409 | 7521 | The merchantCustomerId provided is used in the following number of profiles: 2 |
| 400 | 7523 | Cannot find proper Apple Pay merchant configuration. Apple Pay Processing certificate should be uploaded in Paysafe Backoffice and should match the active Apple Pay Processing certificate from the Apple Developer Portal. |