Errors and limits

Error shape

Two shapes, both from FastAPI. Handle both.

// 401, 404, 409, and 422s raised by a route handler: detail is a STRING
{"detail": "invalid or revoked API key"}
 
// 422s from payload/query validation: detail is an ARRAY
{"detail": [{"type": "extra_forbidden", "loc": ["body", "speed_kph"],
             "msg": "Extra inputs are not permitted", "input": 90}]}

Log loc and type. Do not pattern-match msg — it is prose written for humans and we will keep improving it. type and loc are the machine-readable parts.

By route

POST /v1/events

GET /v1/events

GET /v1/events/{event_id}

POST /v1/events/{event_id}/revisions

POST /v1/events/{event_id}/signals

The 409 deserves a sentence, because it looks like a client bug and is not:

{"detail": "event 7fce24f051e857bfacad005c3f497973 is expired and no longer takes signals"}

It means the hazard is over — the TTL passed, enough vehicles denied it (a deny quorum ends an event as expired; it never marks it invalidated — see Trust), or it was merged. A signal must never resurrect a hazard that is no longer there. It is deliberately not a 404, so you do not go looking for a fault in your id handling. Drop the event from your store and move on; retrying will not help.

GET /v1/stream

Once the stream has begun there is no status code left to send. Two failures are therefore reported inside the stream, as a bye frame:

• {"reason": "snapshot_unavailable", "reconnect": true} — we could not read the initial state. Reconnect; do not read the empty stream as an empty road.
• {"reason": "max_connection_age", "reconnect": true} — the normal scheduled close.

POST /v1/stream/tickets

GET /v1/meta/*, GET /health, GET /

200, no authentication. /v1/meta/* never returns network data.

Limits

curl -s "$RELAY/v1/meta/limits"

{
  "max_query_radius_m": 9780.0,
  "query_level": 5,
  "note": "beyond max_query_radius_m, cover the area with several overlapping queries; route-corridor subscriptions are planned and not available"
}

The "read it from nowhere" rows are current values, not contract. They can change with a deployment. Where an endpoint serves a limit, read it at runtime rather than hardcoding it.

The 500-event cap is the one to watch, because it fails silently: there is no pagination, no cursor and no flag telling you the result was truncated. If you are seeing round numbers near 500, narrow the radius or filter by type.

What is limited, and what is not

Say it plainly, because you will design around it either way:

• One rate limit exists, and it is on signals. POST /v1/events/{id}/signals answers 429 with a Retry-After once an organisation has sent 3000 signals in an hour, on one side of the live/sandbox line. It is a ceiling against a runaway client, not a commercial quota, and it sits far above any normal fleet's rate — if yours approaches it, contact us rather than sharding across keys, because the budget is per organisation and a second key does not buy a second one.
• Nothing else is rate limited. Publishing, reading, opening streams and minting tickets have no ceiling and return no 429. There are no X-RateLimit-* headers anywhere in the API, on any route, including that one.
• There are no quotas. Not on publishing, not on reading, not on open streams, not on ticket minting. One key can mint tickets in a loop.
• Consumption is counted; nothing is refused for being over a plan. Every read, publish, signal and stream connect is metered per organisation, per environment, per day — the counter the commercial model hangs off exists and runs. No code turns a request away for being over a plan, and that order is deliberate: a limit you cannot measure is a limit you will set wrong. The signal ceiling is not an exception to this; it refuses a rate, and it would refuse the same rate on any plan.

Do not read that as permission. The meter is already running, and the contract reserves 429 on every metered route. Build a client that backs off on 429 and on 5xx now, while it is nearly free — a fleet that discovers rate limiting in production discovers it all at once.

Availability

Service-level commitments are a contract matter, set per agreement rather than published as a blanket figure. The engineering target — p95 under one second between publication and reception — holds a wide margin on the reference stack (p95 73 ms); see Streaming.

Retry advice

• 401 — do not retry. Your credential is wrong, or your ticket expired (mint a new one).
• 403, 404, 409, 422 — do not retry. Nothing about the request will succeed on a second attempt. 409 on a signal means the event is over; 409 on a publish means the client_event_id is spent — mint a new id (the one retry that works is resending the original content unchanged, which is the 200 path). 403 means your credential is on the other network and no amount of waiting changes that.
• 429 — retry after the Retry-After header says, not sooner and not in a tight loop. Signals only, and a signal is not urgent: the event is already on the network.
• 5xx, timeouts, connection resets — retry with exponential backoff and jitter. If you are publishing, send the same client_event_id: that is exactly what it is for, and it makes the retry free of duplicates.
• A stream that ends for any reason — reconnect. The fresh snapshot is authoritative, so reconnection is always correct. Browsers on a ticket must mint a new one first; see Streaming.