> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billbooks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error envelope shape and what each error code means

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

```json theme={null}
{
  "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](/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](/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.                                                                                          |

<Tip>
  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.
</Tip>