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

# Error Handling

> HTTP status codes, error response format, and token expiry handling.

All errors return JSON with an `error` field and an appropriate HTTP status code.

```json theme={null}
{ "error": "Missing Bearer token" }
```

## Status codes

| Status | Meaning             | Common causes                                                                                                                                           |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Bad request         | Malformed JSON, missing required fields                                                                                                                 |
| `401`  | Unauthorized        | Missing or expired Bearer token, token not a valid JWT                                                                                                  |
| `403`  | Forbidden           | Invalid API key, API key disabled/expired, token issued for a different client, or missing a required scope if your onboarding instructions require one |
| `413`  | Payload too large   | Request body exceeds 10 MB                                                                                                                              |
| `500`  | Server error        | Unexpected processing error. Email [support@billsentry.com](mailto:support@billsentry.com) with the `x-request-id` value                                |
| `503`  | Service unavailable | Check [billsentry.instatus.com](https://billsentry.instatus.com) for active incidents                                                                   |

<Info>
  Every response includes an `x-request-id` header. Include this value in any support request to [support@billsentry.com](mailto:support@billsentry.com). Check [billsentry.instatus.com](https://billsentry.instatus.com) for live API status and incident history.
</Info>

## Token expiry (401)

Access tokens expire in approximately **1 hour**. When you receive a `401`:

1. Invalidate your cached token
2. Fetch a new token from the Token URL
3. Retry the original request once

<Warning>
  Do not retry indefinitely on `401`. If a second attempt with a fresh token also returns `401`, the issue is likely a misconfigured API key or client binding — contact BillSentry support.
</Warning>

For a complete implementation of token caching, proactive refresh, and 401 retry logic, see [Token Lifecycle](/token-lifecycle).