---
title: "JSON Errors"
description: "Parse Billabex API errors by code, use the resolution hint, and retry only when the response allows it."
canonical: https://developer.billabex.com/en/guides/errors/
lang: en
alternate: https://developer.billabex.com/fr/guides/erreurs/
last-updated: 2026-10-01
---

# JSON Errors

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

Source: https://developer.billabex.com/en/guides/errors/
Language: English (en)
French version: https://developer.billabex.com/fr/guides/erreurs/

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.

```json
{
  "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.

## Two origins, one rule: no HTML errors

The API and this documentation site are two different origins, and both refuse to answer a machine with an HTML page.

- **The API** (`https://next.billabex.com`) answers JSON on every path, error included, in the shape above.
- **The developer portal** (`developer.billabex.com`) serves documents, not JSON. A request to it that prefers `application/json` is refused with `406 Not Acceptable` and a JSON body carrying `code`, `message`, `resolution` and the list of types it does have. A request under `/api/` is redirected to the API with `308`, which preserves the method and the body, so a client that mistakes the documentation host for the API still lands on a JSON answer.

```json
{
  "code": "DOCUMENTATION_NOT_AVAILABLE_AS_JSON",
  "message": "The Billabex developer portal serves documentation as text/html and text/markdown. It has no JSON representation of this path.",
  "resolution": "Request text/html or text/markdown for documentation, read the OpenAPI specification at /openapi.json, or call the Billabex public API, whose every response is JSON.",
  "path": "/en/guides/errors/",
  "method": "GET",
  "type": "http",
  "available": ["text/html", "text/markdown"]
}
```

## Date validation

| Code                                       | Correction                                    |
| ------------------------------------------ | --------------------------------------------- |
| `app-invoicing.date.due-before-issued`     | Choose a due date on or after the issue date. |
| `app-invoicing.date.issued-in-future`      | Choose an issue date no later than today.     |
| `app-dunning.email.scheduled-date-invalid` | Provide a valid send date and time.           |
| `app-dunning.email.scheduled-date-in-past` | Choose a future send date and time.           |

---

Billabex developer portal. OpenAPI specification: https://developer.billabex.com/openapi.json.
Agent instructions: https://developer.billabex.com/llms.txt. Complete documentation: https://developer.billabex.com/llms-full.txt.