Errors & Status Codes
| HTTP | Meaning | Envelope |
|---|---|---|
200 | Success — fresh enough data | { status: "SUCCESS", data: {...}, error: null, meta: {...} } |
200 | Stale data — older observation, still real | { status: "STALE_DATA", data: {...}, error: null, meta: {...} } |
400 | Invalid train number, date or query | { status: "INVALID_REQUEST", error: { code, message } } |
401 | Missing or invalid x-api-key header | { data: null, error: { code, message }, meta: {...} } |
404 | Unknown train, station or no match | { status: "TRAIN_NOT_FOUND" | "STATION_NOT_FOUND" | "NOT_FOUND", error: { code, message } } |
404 | Unknown, flushed or expired PNR | { status: "PNR_NOT_FOUND", error: { code, message } } |
429 | More than 60 requests per minute | { status: "RATE_LIMITED", error: { code, message } } |
500 | Internal error | { data: null, error: { code, message }, meta: {...} } |
503 | Upstream data source unavailable | { status: "PROVIDER_UNAVAILABLE", error: { code, message } } |
Common Error Scenarios
Missing x-api-key header or invalid key (401)
Malformed train number, date or query (400 INVALID_REQUEST)
Train or station not found (404)
Flushed or expired PNR (404 PNR_NOT_FOUND)
More than 60 requests per minute (429 RATE_LIMITED)
Upstream outage — retry with backoff (503 PROVIDER_UNAVAILABLE)
Network failures and timeouts — handle with try/catch