Errors

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Format

All error responses return a JSON object with a detail field:

json

{ "detail": "Error message describing what went wrong" }

Status Codes

Code	Meaning	Common Causes
400	Bad Request	Missing required parameters, invalid date format, race number out of range
401	Unauthorized	Missing or invalid API key, expired key
403	Forbidden	API key valid but insufficient tier for this endpoint
404	Not Found	No race data for that date/track/race combination, unknown venue
429	Too Many Requests	Daily rate limit exceeded
500	Internal Error	Server-side error — contact support if persistent

Getting 404s on /v1/form?

A 404 means no race matched that exact date, track slug, and race number — not that your key or request is malformed. Before requesting form, call the meetings endpoint to confirm what's running on your date, then copy the exact slug and raceNumber from its response. Most 404s come from guessing a track slug or requesting a race number that isn't on the card.

Error Examples

Missing required parameter:

400

Response

json

{ "detail": "Missing required parameter: date" }

Invalid API key:

401

Response

json

{ "detail": "Invalid or missing API key" }

Rate limit exceeded:

429

Response

json

{ "detail": "Rate limit exceeded. Check Retry-After header." }

Rate Limiting

When you receive a 429 response, read the Retry-After header for the exact number of seconds until the next slot opens. FormFav uses a rolling 24-hour window — not a midnight reset. See the Rate Limiting guide for details.

Monitor your usage with the X-RateLimit-Remaining-Day response header to avoid hitting limits.