Errors

The Checkbook API communicates the outcome of your requests using standard HTTP status codes. These codes provide a high-level indication of success or failure. However, for more granular details about what went wrong, especially in cases of failure, the API also returns informative error messages within the response body. This page explains how to interpret both the HTTP status codes and the structured error messages to effectively handle API responses in your application.

Response Codes

The Checkbook API uses standard HTTP status codes to indicate the outcome of your requests. Here’s a summary of the most common status codes you might encounter:

Success Responses (2xx)

Code	Message	Details
`200`	OK	The request was successful, and the server has returned the requested data. This is the standard success response for GET requests.
`201`	Created	The request was successful, and a new resource has been created. This is typically returned after a successful POST request.
`204`	No Content	The request was successful, but the server is not returning any content. This is often returned after a successful DELETE request or a PUT request that updates a resource without changing its representation.

Client Error Responses (4xx)

Code	Message	Details
`400`	Bad Request	The server could not understand the request due to invalid syntax or missing required parameters. Check your request body and parameters for errors. The response body often provides more specific details about the issue.
`401`	Unauthorized	Authentication failed. This indicates that you have not provided valid authentication credentials (e.g., an incorrect, expired or missing API key). Ensure your `Authorization` header is correctly formatted with a valid API key.
`403`	Forbidden	The server understands the request but refuses to authorize it. This usually means your API key does not have the necessary permissions to perform the requested action on the specific resource.
`404`	Not Found	The requested resource could not be found on the server. Verify the endpoint URL and resource identifier.
`405`	Method Not Allowed	The HTTP method used in the request is not supported for the specified resource. Check the API documentation for the allowed methods for that endpoint.
`409`	Conflict	The request could not be completed due to a conflict with the current state of the resource. This might occur if you try to create a resource with a unique identifier that already exists. The response body will usually provide details about the conflict.
`429`	Too Many Requests	You have exceeded the rate limit for the API. You may need to implement retry logic with exponential backoff or contact support to discuss higher rate limits.

Server Error Responses (5xx)

Code	Message	Details
`500`	Internal Server Error	An unexpected error occurred on the server. This is a general error, and the Checkbook team is typically notified of such issues. If you encounter this consistently, please contact support with details of your request.
`503`	Service Unavailable	The server is currently unavailable due to maintenance or overload. This may occur when printing a check if the print endpoint is called before the check images have had time to generate. You may need to retry your request after some time.

Error Messages

When an error occurs, the Checkbook API returns a JSON response to help you understand the reason for a failure. This response object contains information about the error, allowing your application to handle it gracefully.

The response object includes the following fields:

error (String): This field provides a human-readable description of the error, giving you specific details about what went wrong.

more_info (Object, Optional): If the error is related to specific parameters in your request, this field will indicate which parameter(s) caused the issue.

Example Error Response


{
  "error": "JSON body parameters are invalid.",
  "more_info": {
    "amount": "Must be greater than or equal to 0.01."
  }
}