Copy page

Documentation

Errors

Errors

The AirTrack API uses conventional HTTP status codes and a single, predictable error envelope, so you can handle failures the same way everywhere.

The error envelope

Every handled error returns a JSON body with a single detail string describing what went wrong:

Code
{ "detail": "Your token lacks the required scope" }

Every handled status uses this shape, including 422 — where detail is a fixed "Request validation failed" for body validation, because the offending input is deliberately not echoed back. The one exception is 500, which returns the plain text Internal Server Error.

Status codes

Status	Meaning	Body
400	Bad request — for example an invalid forecast date, a route that exceeds the maximum plan distance, or waypoint times outside the window air-quality data exists for.	{ "detail": … }
401	Missing, unknown or revoked token; or an invalid/expired pairing code.	{ "detail": … }
403	Your token isn't permitted to perform this operation — usually a missing scope, or the owning user no longer holding a premium plan. The exact causes vary per endpoint; see its own description.	{ "detail": … }
404	No such resource, or it belongs to a different AirTrack user — for example polling a route-plan request_id created by someone else. Plans are owned by the user, not the connection, so your other connections can poll them.	{ "detail": … }
422	The request failed validation — the body, or a path parameter such as an invalid request_id.	{ "detail": … }
429	Rate limited, or your credit pool (monthly or daily burst) is exhausted.	{ "detail": … } + Retry-After
503	An upstream data source was unavailable — the call was not charged.	{ "detail": … }

Rate limits & credits

Endpoints that compute air quality draw from one shared monthly credit pool, with a smaller daily burst cap so the whole month can't be spent at once — costs per endpoint are on the Usage & credits page. Redeeming a pairing code, reading GET /v1/quota and polling for a route-plan result are free. When either limit is reached, calls return 429 with a Retry-After header giving the number of seconds to wait. Check your current balance any time with GET /v1/quota.

Calls that fail before delivering a result — a 503 upstream outage, or a route plan rejected for being too long — are refunded automatically, so a failed request never costs you credits.

Handling errors in code

Branch on the status code, honour Retry-After on a 429, and read detail for a human-readable reason. This helper retries rate-limited calls and raises on anything else:

For how to obtain and secure a token, see Authentication. For runnable examples of each endpoint, see the Quickstart.