Errors

Every failed request returns the same envelope shape, an HTTP status code that matches the failure, plus a JSON body:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Some fields need attention.",
    "fields": {
      "qty": "must be greater than 0"
    }
  }
}

fields is only present when code is validation_error, it’s a map of field name to a plain-English problem description.

Error codes

Code	What it means
`invalid_request`	The request itself is malformed, bad JSON, missing required structure.
`unauthorized`	Your API key is missing, malformed, unknown, revoked, or expired. See Authentication, all of these return the same generic message on purpose.
`not_found`	The resource doesn’t exist, or belongs to a different organization than your key’s (from your key’s perspective, those look identical).
`validation_error`	One or more fields failed validation. Check the `fields` object for specifics.
`conflict`	Something you’re creating collides with something that already exists, for example, reusing an invoice `no` that’s already in use in your organization.
`rate_limited`	You’ve hit the per-resource rate limit. See Rate Limits.
`method_not_allowed`	You used an HTTP method the endpoint doesn’t support.
`server_error`	Something went wrong on Billbooks’ side. If this persists, get in touch.

Since not_found covers both “doesn’t exist” and “belongs to someone else,” you can’t use it to probe whether a given ID exists in another organization, both cases look the same from the outside.

⌘I

Get Started

How-to guides

Error codes

​Error codes

Error codes