Errors

The Quickbook API uses conventional HTTP status codes and returns a consistent JSON error body so failures are easy to handle programmatically.

Error response format

Most errors are returned as an application error envelope:

{
  "status": "400",
  "code": "BAD_REQUEST",
  "type": "Validation Error",
  "time": "2026-07-12T09:15:03Z",
  "message": "The request could not be processed.",
  "description": "`payment_method` is required.",
  "reference_id": "b2f1c0a4-8e2d-4a71-9e0b-2f6c1a5d8e90"
}

The reference_id matches the x-transaction-id response header — quote it in any support request. See Transaction IDs.

Authentication policy failures use a simpler shape:

{
  "error": "invalid_client",
  "description": "wrong client_id or client_secret"
}

Status codes

Status	Meaning	When it happens
400	Bad Request	The request is malformed or contains invalid data.
401	Unauthorized	Invalid client_id or client_secret — see Authentication.
403	Forbidden	Missing/invalid Authorization header, or the operation is not permitted.
404	Not Found	The requested URI doesn't exist or isn't mapped in the API.
405	Method Not Allowed	The HTTP method isn't supported by the target resource.
406	Not Acceptable	The API can't produce a representation matching the Accept header.
415	Unsupported Media Type	The request body format isn't supported for the method used.
429	Too Many Requests	The rate limit was exceeded — see Rate limits.
500	Internal Server Error	The API failed due to a server internal error.
502	Bad Gateway	An upstream service failed and couldn't process the request.
504	Gateway Timeout	The API didn't receive a timely response from another service.
520	Backend Error	The backend failed due to a server internal error.

Error codes and types

The code and type fields carry machine-readable classifications:

• code — one of BAD_REQUEST, UNHOUTORIZED, FORBIDDEN, RESOURCE_NOT_FOUND, METHOD_NOT_ALLOWED, NOT_ACCEPTABLE, CONFLICT, UNSUPPORTED_MEDIA_TYPE, INTERNAL_SERVER_ERROR, BAD_GATEWAY, GATEWAY_TIMEOUT, BACKEND_ERROR.
• type — one of Contract Violation, Validation Error, System Error, Upstream Service Error, Connection Error, Authorization Error, Backend Error.

In the API Reference

Each operation documents its specific error responses. Expand the responses for any endpoint in the API Reference to see them.