Skip to main content
All errors return JSON with an error field and an appropriate HTTP status code. 
{ "error": "Missing Bearer token" }

​
Status codes

StatusMeaningCommon causes
400Bad requestMalformed JSON, missing required fields
401UnauthorizedMissing or expired Bearer token, token not a valid JWT
403ForbiddenInvalid API key, API key disabled/expired, token issued for a different client, missing billreview:write scope
413Payload too largeRequest body exceeds 10 MB
500Server errorUnexpected processing error. Contact support with the x-request-id value
503Service unavailableCheck status.billsentry.net for active incidents
Every response includes an x-request-id header. Include this value in any support request. 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:
  1. Invalidate your cached token
  2. Fetch a new token from the Token URL
  3. 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.