What do MileCheck API errors and rate limit headers mean?

Headers on every response

Header	Meaning
`X-Request-Id`	Unique to this call, like `req_9f2c…`. Error bodies repeat it as `request_id`. Send it to info@milecheckapp.com and we can find the call.
`X-RateLimit-Limit`	Calls allowed per UTC day on this key. Not sent for keys with no daily limit.
`X-RateLimit-Remaining`	Calls left today, after this one.
`X-RateLimit-Reset`	When the count resets, in epoch seconds. Always the next UTC midnight.
`Retry-After`	On a 429 only: seconds until the reset.

Browsers can read all of these headers across origins. To check your numbers without spending a call, use GET /v1/usage.

Error body

The old error text is still there. New clients should match on code.

HTTP/1.1 401
X-Request-Id: req_9f2c41d07a3b5e8c1d20

{
  "error": "Invalid API key.",
  "code": "invalid_api_key",
  "message": "Invalid API key.",
  "docs": "https://milecheckapp.com/api/errors/#invalid_api_key",
  "request_id": "req_9f2c41d07a3b5e8c1d20"
}

Error codes

Code	Status	Cause and fix
`missing_api_key`	401	No key sent. Use `?apikey=`, an `x-api-key` header, or `Authorization: Bearer`.
`invalid_api_key`	401	The key is not one we issued. Check for a trailing space or a rotated key.
`key_inactive`	402	The key was turned off, usually a cancelled subscription. Email sales@milecheckapp.com.
`key_expired`	403	A test key ended (14 days) or a key passed its end date. Email sales@milecheckapp.com to start a plan. `GET /v1/usage` still works and shows the end date.
`state_not_available`	403	This source is not available for that state or province. The body names the state and the reason.
`forbidden`	403	The call is not allowed for this key.
`unsupported_state`	404	The state or province code is not one we cover. The body lists the supported codes.
`not_found`	404	No such endpoint or record.
`method_not_allowed`	405	Wrong HTTP method. The message says which to use.
`invalid_parameter`	400 or 422	A parameter is missing or out of range, such as `lat` without `lon`. The message names it.
`bad_request`	400	The request could not be read.
`rate_limit_exceeded`	429	The daily limit for this key is used up. Wait for `Retry-After` seconds, or ask for a higher limit.
`upstream_unavailable`	502 or 503	The source feed (a state DOT, CBP and so on) is not answering. Retry in a minute. Feed health is also in `source_status` on successful responses.
`internal_error`	500	Our side failed. Retry once; if it repeats, send the request id.

What counts against your limit

Every authenticated call that reaches the limit check counts, including ones that then return a 4xx for a bad parameter. Unauthenticated calls, /v1/health and GET /v1/usage do not. A call refused with 429 is not counted again.

Retry on 429 and 5xx with a pause. Do not retry other 4xx errors; they will fail the same way.

Our mission

Become the trusted source for road information across North America, from today’s closures to next season’s roadwork.

What we do

We put every state’s Department of Transportation data in one place, on your phone, in your car and in your browser.

Our values

No ads in the app. Our website is free to use, so it has a clearly marked sponsor slot to help pay for it, without pop-ups.
Road data, not your data. We collect road data from state DOTs, not data about you. You don’t need an account, your mile marker is calculated on your phone, your trip history stays there, and we never sell your data.
Only what’s needed. Weather sends your approximate location to the National Weather Service, route planning sends your location and destination to Google, and wildfire alerts send a location rounded to about 7 miles only if you turn them on. Sentry receives anonymous crash reports, we count feature use without location or identity, and Apple or Google handles subscriptions.
Built for real roads. Nearly every feature exists because someone on a real road asked for it.

More in our privacy policy and our story.