Errors

Errors use standard HTTP status codes and a small JSON body.

{ "error": "invalid lap_time_ms" }

Some errors add fields that help you recover, for example required_scope or retry_after_s. Match on the HTTP status first, then on error where you need detail. Messages are stable for the cases listed below but may gain new variants.

Status codes

Status	Meaning	What to do
200	Success.	n/a
400	The request was malformed or failed validation.	Fix the request. Don’t retry unchanged.
401	Missing, invalid or revoked API key.	Check the key and the Authorization header.
403	Key is valid but not allowed: wrong club, or missing scope.	Use a key for the event’s club, or one with the right scope.
404	Unknown path, or an event that isn’t public or doesn’t belong to you.	Check the ID. Private events return 404 to unauthenticated reads.
405	Wrong HTTP method (Track API and key creation).	Use GET (Track API) or POST (key creation).
413	Stream packet too large.	Send at most 5,000 lines or 2,000 passings per request.
429	Rate limit exceeded.	Wait Retry-After seconds. See rate limits.
500	Server or database error. error carries the message.	Retry with exponential backoff.
503	Health check reports a degraded dependency.	Retry later.

Validation messages

Laps

error	Cause
laps must be an array	Body missing, not JSON, or laps isn’t an array.
laps array is empty	laps is [].
max 1000 laps per request	More than 1,000 laps in one request.
invalid lap_number	lap_number missing, not a number, or negative.
invalid lap_time_ms	lap_time_ms missing, zero or negative, or more than 24 hours.

Streams

error	Cause
invalid json body	The body couldn’t be parsed.
unknown vendor	vendor isn’t orbits, trackside, axware, rmonitor or generic.
lines or passings required	Both arrays are empty or missing.
packet too large	More than 5,000 lines or 2,000 passings (status 413).

Penalties and sessions

error	Cause
penalties must be an array	penalties missing or not an array.
invalid status	Session status isn’t scheduled, live or finished.

Retrying safely

• 429: honour the Retry-After header.
• 5xx: retry with exponential backoff and jitter (1 s, 2 s, 4 s … capped at 30 s).
• Network errors: retry, but remember POST /laps is not idempotent. The stream endpoint de-duplicates for you, so prefer it for continuous feeds.
• 4xx other than 429: don’t retry. The request will fail the same way.