Core concepts

Errors and retries

Stable codes and retry decisions.

Error envelope

JSON
{
  "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.

Validation details

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.

JSON
{
  "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.

Categories

Category, Typical HTTP, Action table
CategoryTypical HTTPAction
VALIDATION400 or 422Fix the request. Never retry unchanged. A 422 means the journey itself can't be enquired (quota, class, run day, booking window).
AUTH401 or 403Fix or rotate the credential, or check the key's IP allowlist, scopes and plan status.
FORBIDDEN403Move to a plan that includes the endpoint.
QUOTA402Wait for renewal or change plan.
RATE_LIMIT429Honor Retry-After and add jitter.
NOT_FOUND404, 409 or 410Verify identifiers. Chart pending can be retried later.
UPSTREAM503Wait for Retry-After, then retry with bounded exponential backoff.
INTERNAL500 or 503Retry with backoff and alert if persistent.

Upstream failures answer 503

When a live-data source fails or times out, the API answers 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.

Retry policy

Node.js
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

Use approximately 500 ms, 1 s, 2 s, and 4 s with jitter. Honor Retry-After on 429 and 503 responses and stop after five attempts.

Debugging checklist

  1. 1. Log the response status, error.code, and X-RailCore-Request-ID.
  2. 2. Verify the key scope and plan entitlement for this route.
  3. 3. For signature failures, print the exact canonical payload without the secret.
  4. 4. For repeated live-data failures, check status.railcore.tech.
  5. 5. Include the request ID in a support message within the seven-day request-log window.

Last updated