Best Practices

JSON Errors

Parse Billabex API errors by code, use the resolution hint, and retry only when the response allows it.

Structured JSON errors

Billabex API errors use JSON. Do not branch on an HTML page or a translated user-facing message. Read the HTTP status and the stable code, then use details, resolution, and response headers to decide what to do next.

{
  "message": "Invalid or missing OAuth token",
  "code": "HTTP_401",
  "frontMessage": "Authentication required",
  "timestamp": "2026-08-24T18:09:55.818Z",
  "path": "/api/public/v1/organizations",
  "type": "http",
  "method": "GET",
  "resolution": "Obtain a valid OAuth access token and retry."
}

Fields

Field Meaning
message Technical explanation for logs and developers.
code Stable machine-readable code. HTTP errors use HTTP_<status>; business errors use their domain or application code.
frontMessage Optional localized message for a user interface. Do not use it for control flow.
details Optional structured values attached to a business error, such as the calculated and maximum credit cost.
timestamp UTC time at which the API produced the error.
path and method Request target that failed.
type Error source: http, app, domain, infra, or unknown.
resolution Safe next action for an automated client.

Retry rules

  • For 400, correct the request before retrying. Unknown input fields are rejected rather than ignored.
  • For 401, obtain a valid access token through OAuth and retry once.
  • For 403, request one of the scopes declared for the OpenAPI operation and authorize the client again.
  • For 404, verify the endpoint and resource identifier. Repeating the same request will not fix it.
  • For 429, wait for the Retry-After header and monitor the RateLimit headers.
  • For 5xx, use bounded retries with backoff. Contact Billabex support if the error persists.

The OpenAPI specification links error responses to the same typed schema, so generated clients and function-calling tools can parse these fields without scraping documentation.