API errors
Every error returned by the JSON API uses a single envelope,RFC 9457 problem details, served as application/problem+json. Branch on the code field; type links back to this page. This applies to GET requests on the routes documented in/openapi.json. /bulletin/* is a separate HTML page surface, outside this envelope; other methods, or a malformed request, get a plain HTTP error instead.
{
"type": "https://portail.chom.engineering/errors#station-not-found",
"title": "Station not found",
"status": 404,
"detail": "unknown station: 07156001",
"instance": "/v2/journaliere?station=07156001",
"code": "station-not-found",
"details": {
"station": "07156001"
},
"request_id": "4f2a9c1b7e3d0a5b8c1d2e3f40516273"
}request_id
Every response on this envelope — errors and successes alike — carries an X-Request-Id header, repeated as request_idin error bodies. Quote it when reporting an incident: it is the only value that ties what you received to what the server logged.
What is not an error
An empty result is not an error. A canonical station, including a published alias, with no measurement over the requested window returns 200 with n = 0 andmesures: []. Only an identifier absent from the canonical reference returns station-not-found; quarantined or out-of-reference identifiers are never promoted to canonical stations.
Status codes
| Case | Status |
|---|---|
| Parameter missing or malformed | 400 |
| Unknown station, dataset, territory, route or document | 404 |
| No data over the requested window | 200, n = 0 |
| Warming up, or pool saturated | 503 + Retry-After |
| Coverage not computed yet | 503, no Retry-After — recomputed daily |
| Internal fault | 500 |
Catalogue
dataset-not-found 404
Dataset not found
The dataset segment of the path belongs to no published table of that family. `details.datasets` lists the ones actually served.
document-not-found 404
Document not found
A static document (`/openapi.json`, `/llms.txt`, `/llms-full.txt`) is not deployed on this server. This is an operational fault, not a client error — please report it.
internal-error 500
Internal error
An unexpected fault. The cause is logged server-side against the `request_id` returned here; quote it when reporting the incident.
invalid-parameter 400
Invalid parameter
A query parameter is present but malformed — a date outside `YYYY-MM-DD`, an unknown output format. The value is not interpreted and no partial result is returned.
malformed-request 400
Malformed request
The request could not be parsed: bad request line, unsupported HTTP version, over-long URI or headers. The HTTP status follows what the protocol layer decided (400, 414, 431 or 505) and the `status` member repeats it. `details.reason` carries the parser's own wording.
method-not-supported 501
Method not supported
The service answers `GET` only. `details.method` repeats the verb that was used. Emitted by the protocol layer, before any route is matched — so it does not appear in the per-route responses of the OpenAPI document, which describe `get` operations.
missing-parameter 400
Missing parameter
A required query parameter is absent. The `details` object names the parameter and, where applicable, the accepted values.
no-current-value 404
No current value
The live tier holds no last known value for this station: the identifier may be unknown, outside the 24-month rolling window, or absent from the requested network. The service cannot tell these three apart — hence a distinct code from `station-not-found`, which does mean « absent from the reference dataset ».
route-not-found 404
Route not found
No handler matches this path. `details.routes` lists the served routes and `details.datasets` the tables of each family.
schema-not-ready 503
Station reference schema not ready
The station reference Gold table has not yet been rebuilt with the schema required by this serving version. Rebuild `gold_ref.station` with `aliases` as an array of strings, then retry the request.
service-saturated 503
Service saturated
Every DuckDB cursor in the pool is busy. Back off and retry; this is a load signal, not a fault.
service-warming-up 503
Service warming up
The service binds the port before it is ready — about 1.4 s at startup. Retry after the `Retry-After` header; `details.retry_after_s` repeats the value.
station-not-found 404
Station not found
The identifier matches no canonical station or published alias in the reference dataset. Resolve it with `/stations?q=` or `/ref/stations`. Identifiers explicitly quarantined or classified outside the reference are not canonical. A known station with no data over the requested window is not this error: it returns 200 with `n = 0`.
territory-not-found 404
Territory not found
The INSEE or SIREN code is absent from the heatwave tables — either unknown, or present but never measured. `details` carries `level` and `insee_code`.
upstream-licence-restricted 451
Upstream licence forbids redistribution
The request asks for upstream data this service is not allowed to redistribute. Emitted by `/ref/stations-legacy?display_closed=1`: the stations that parameter adds are those the upstream feed publishes under licence code 3 — « CLOSED: NO REDISTRIBUTION ALLOWED » — plus those whose licence is unset upstream, which the upstream contract declares excluded from open data. `details.upstream` carries the feed URL: query it directly if you need them. 451 rather than 501 because the obstacle is not implementation, it is the licence.
weather-ai-history-invalid 502
Weather AI history invalid
An immutable historical registry entry failed integrity or contract verification, so no partial history is returned.
weather-ai-history-run-not-found 404
Weather AI historical run not found
The requested run is absent from the immutable local registry or its catalogue was published outside the rolling thirty-day window.
weather-ai-product-integrity-failed 502
Weather AI product integrity failed
The Gold object bytes do not match the SHA-256 recorded by the validated catalog, so no data is returned.
weather-ai-product-invalid 502
Weather AI product invalid
The digest-verified Gold object does not satisfy the pinned cartography product contract, so no data is returned.
weather-ai-product-not-found 404
Weather AI product not found
The requested `product_id` is absent from the last validated Weather AI publication catalog. `details.products` lists the ones currently served — all experimental, none carrying alert authority.