Errors

TransitKit returns proper HTTP status codes and a consistent JSON error shape for all error responses. No more digging through systemMessages in 200 OK responses.

Error Shape

All errors return this consistent JSON structure:

Error Response

{
  "error": {
    "code": "INVALID_STOP",
    "message": "No stop found with ID '99999'. Use /v1/stops/search to find valid stop IDs.",
    "docs": "https://transitkit.dev/docs/errors#INVALID_STOP"
  }
}

Error Codes

HTTP Status	Error Code	Description
401	UNAUTHORIZED	Missing or invalid API key
400	INVALID_STOP	Stop ID not found in TfNSW system
400	MISSING_PARAM	Required parameter not provided
429	RATE_LIMITED	Daily request limit exceeded
503	UPSTREAM_ERROR	TfNSW API unavailable

Compared to TfNSW

The raw TfNSW API returns HTTP 200 for nearly all responses, including errors. Error information is buried in a systemMessages array within the response body. Your HTTP client treats these as successful responses, making error handling unreliable.

TransitKit translates these into proper HTTP status codes so you can use standard error handling patterns in any language.