# Where the contract and the API disagreed, they now agree

A check of the published contract against the live API found a dozen differences. A few were fixed in the API, and the rest in the contract.

Sep 21, 2026 · Fixed

We replayed the published contract against the live API and wrote down every place where they disagreed. Where the API was wrong, the API changed. The first four highlights are those, and they are the only ones where a response differs from before. Where the document was wrong, the document changed and the server behaves as it always did.

## What else changed

- **`logo_url` on a company is an absolute URL.** `GET /v1/companies/{company_id}` returned a storage path for a logo uploaded through the logo endpoint. It now returns the same fetchable URL as the invoice-customization resource and an invoice's `issuer.logo_url`.
- **A number field that receives text answers `400 INVALID_JSON_FORMAT` with `details` filled in**: `field`, `invalid_value` and `expected_format` (`number` or `integer`). It used to come back with `details: {}`.
- **A deprecated route that rejects an unknown query parameter still sends `Deprecation` and `Sunset`** on that `400`, like on any other answer from it.
- **A property that breaks two rules at once gets one stable message** with both reasons, instead of one of the two, picked differently on identical calls.
- **Contract corrections, server unchanged:** `GET /v1/accounts/{account_id}/companies` is always paginated and always carries `pagination`. A value outside an enum in a **body** answers `422 VALIDATION_ERROR` with `allowed_values`, not `400`. `POST …/customers` can answer `422 NIF_NOT_IN_CENSUS`. A body property the operation does not declare is ignored without a warning.
- **`404` and `409` name what failed.** The contract now lists the codes the API already returned, such as `INVOICE_NOT_FOUND`, `CLIENT_NOT_FOUND`, `CLIENT_DUPLICATE` and `ENDPOINT_NOT_FOUND`, in place of a generic `NOT_FOUND` or `CONFLICT` that it never sent.

## Where to go next

- [Handling errors](/guides/handling-errors)
- [INVALID_JSON_FORMAT](/errors/INVALID_JSON_FORMAT)
- [List the companies of an account](/companies/listCompanies)

---

Full OpenAPI spec: https://docs.beel.es/api/openapi