Core concepts
Stable codes and retry decisions.
{
"success": false,
"error": {
"code": "STATION_NOT_FOUND",
"message": "Station ZZZZ not found. Check the station code.",
"category": "NOT_FOUND",
"retryable": false,
"details": []
},
"meta": {
"api_version": "v1",
"request_id": "req_01J...",
"trace_id": "trc_01J...",
"timestamp": "2026-11-20T10:57:12.785Z"
}
}A 404 names what was not found: Station ZZZZ not found. Check the station code. or Train 99999 not found. Check the train number.
A 400 VALIDATION_ERROR lists each problem in error.details. field names the parameter or body field, with its place in a list where it has one.
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "'match' must be city or station",
"category": "VALIDATION",
"retryable": false,
"details": [
{
"field": "match",
"issue": "'match' must be city or station"
}
]
}
}Other values of field include date, items[2].date and callback_url.
| Category | Typical HTTP | Action |
|---|---|---|
| VALIDATION | 400 or 422 | Fix the request. Never retry unchanged. A 422 means the journey itself can't be enquired (quota, class, run day, booking window). |
| AUTH | 401 or 403 | Fix or rotate the credential, or check the key's IP allowlist, scopes and plan status. |
| FORBIDDEN | 403 | Move to a plan that includes the endpoint. |
| QUOTA | 402 | Wait for renewal or change plan. |
| RATE_LIMIT | 429 | Honor Retry-After and add jitter. |
| NOT_FOUND | 404, 409 or 410 | Verify identifiers. Chart pending can be retried later. |
| UPSTREAM | 503 | Wait for Retry-After, then retry with bounded exponential backoff. |
| INTERNAL | 500 or 503 | Retry with backoff and alert if persistent. |
Upstream failures answer 503
503 with UPSTREAM_UNAVAILABLE or UPSTREAM_TIMEOUT, a Retry-After header and the usual request ID. The request is not counted. Because METERING_UNAVAILABLE is a 503 too, branch on error.code, not the status.function shouldRetry(status, error, attempt) {
if (attempt >= 5) return false;
if (status === 429) return true;
return [
"UPSTREAM_UNAVAILABLE",
"UPSTREAM_TIMEOUT",
"METERING_UNAVAILABLE",
"INTERNAL",
].includes(error.code);
}Recommended backoff
error.code, and X-RailCore-Request-ID.Last updated