Error Response Format
When errors occur, the Errors object within the response Meta will contain a detailed explanation of the error. Each error is comprised of an ErrorCode and an ErrorMessage. The former identifies the error type and the latter provides specific information about the error.
The Message in the ErrorMessages array is information that would be helpful to display to the user of your system in order to attempt to resolve the issue.
{
"Meta": {
"Errors": { // If not null, an error has occurred
"ErrorCode": "InvalidInput", // Type of error, see Error Codes below
"ErrorMessages": [{ // Array can contain multiple errors
"Field": "RoutingNumber", // Input field with invalid data
"Message": "Invalid Routing Number." // Description of error. You can display this to the user.
}],
"TraceCode": null
},
"HttpStatus": "BadRequest", // HTTP status code description
"HttpStatusCode": 400, // HTTP status code returned
"PagingDetails": null // Always null when error
},
"Response": null // Always null when error
}
Logging Errors
Creating a log to capture any API errors is strongly recommended. It will be extremely helpful when you work with our API Support Team to troubleshoot errors. Be sure to log the exact timestamp of when the error occurred, the full error message and any available ids for error context.
Error Codes
| Error Code | Description | Http Status Code |
|---|---|---|
| InvalidInput | This is the most common error type, and occurs if there is a problem with the data entered in the Request. The ErrorMessage provided for this ErrorCode details the problem, and provides a text explanation that can be displayed directly to the User | 400 Bad Request |
| InvalidPermissions | Permission is denied to perform this action | 403 Accesss Denied |
| NotFound | The requested information cannot be found. It may not exist or may have been deleted | 404 Not Found |
| UnexpectedError | System Error. Check for coding errors and then try again. If the error persists, note the Trace Code included in the error and provide it to PaySimple API Support for assistance. This can also be caused by errors in formatting the Authorization Header. | 500 Internal Server Error |
Missing or Improper Field Values
This type of error typically occurs when you have failed to include a required field in request.
ErrorCode: InvalidInput
ErrorMessage:
Field: "{Name of the missing field}"
Message: "{Display-ready detailed error message}"
NOTE: If ShippingSameasBilling is omitted it defaults to “false” and thus ShippingAddress must be included.
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "ShippingAddress",
"Message": "ShippingAddress is required when ShippingSameAsBilling is false"
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "",
"Message": "Amount must be greater than 0"
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "RoutingNumber",
"Message": "Invalid Routing Number."
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "",
"Message": "Company Name is required for all CCD transactions."
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
Id Reference Errors
This type of error typically occurs when you attempt a Request that includes a Customer, Account, or Payment Id that does not exist for the Client Account.
ErrorCode: InvalidInput
ErrorMessage:
Field "" (empty)
Message "{Display-ready detailed error message}"
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "",
"Message": "Specified Customer Account Id is not valid"
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "",
"Message": "Customer with ID 219175 does not belong to client"
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "",
"Message": "Account with ID 394099 has been deleted"
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
Customer Not Found Errors
This type of error occurs when you attempt to edit a deleted Customer Object.
ErrorCode: NotFound
ErrorMessage:
Field "" (empty)
Message "{Display-ready detailed error message}"
{
"Meta": {
"Errors": {
"ErrorCode": "NotFound",
"ErrorMessages": [{
"Field": null,
"Message": "Customer 260860 was not found, or has been deleted"
}],
"TraceCode": null
},
"HttpStatus": "NotFound",
"HttpStatusCode": 404,
"PagingDetails": null
},
"Response": null
}
Unavailable Functions
This type of error occurs when you attempt a function that cannot be completed. For example, you’ll see this error type if you attempt to delete a payment account attached to an active schedule or attempt to delete a Customer associated with unsettled payments.
ErrorCode: InvalidInput
ErrorMessage:
Field "" (empty)
Message "{Display-ready detailed error message}"
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "",
"Message": "There are still unsettled transactions outstanding for this Customer. It cannot be deleted.”
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
Improper Methods
This type of error occurs when you attempt a Route not supported by the API, such as attempting to delete a Payment Object; or when the system detects that you are using an incorrect method, such as using the POST method when trying to update an Object instead of the PUT method.
When using an unsupported Route, the Response Body will contain an error message describing the problem.
When the system detects what it identifies as an incorrect method, you will see a full error message:
ErrorCode: InvalidInput
ErrorMessage
Field "Id"
Message "Id cannot have a value, did you mean to execute a PUT operation?"
{
"Message": "The requested resource does not support http method 'DELETE'."
}
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "Id",
"Message": "Id cannot have a value, did you mean to execute a PUT operation?"
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
Trace Errors
When an error occurs and the system cannot immediately identify the cause it creates a Trace that the PaySimple team can view to help troubleshoot the problem. The Trace Number is returned as part of the API error message.
In some cases, typically when the error is due to an unexpected User input, this Trace Number is displayed in the ErrorMessage field so that it can be passed along to the User. The User can then call customer support and provide the Trace Number so that the problem can be investigated.
In other cases, typically when the error is at the system level, the Trace Number is provided in the TraceCode field included in the error message. An example of each case is provided below.
{
"Meta": {
"Errors": {
"ErrorCode": "InvalidInput",
"ErrorMessages": [{
"Field": "",
"Message": "CM-003: An unknown error occurred while processing your request. Please contact customer service. Trace number is '8D0AE88CCB92CF0'."
}],
"TraceCode": null
},
"HttpStatus": "BadRequest",
"HttpStatusCode": 400,
"PagingDetails": null
},
"Response": null
}
{
"Meta": {
"Errors": {
"ErrorCode": "UnexpectedError",
"ErrorMessages": [],
"TraceCode": "API8D0AE891FE42F3D"
},
"HttpStatus": "InternalServerError",
"HttpStatusCode": 500,
"PagingDetails": null
},
"Response": null
}