Error Handling - BillSentry API

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

{ "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 with the `x-request-id` value
`503`	Service unavailable	Check billsentry.instatus.com for active incidents

Every response includes an x-request-id header. Include this value in any support request to support@billsentry.com. Check billsentry.instatus.com for live API status and incident history.

Token expiry (401)

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

Invalidate your cached token
Fetch a new token from the Token URL
Retry the original request once

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.

For a complete implementation of token caching, proactive refresh, and 401 retry logic, see Token Lifecycle.