API errors

Headcode APIs return errors using RFC 9457 Problem Details for HTTP APIs.

Error responses use the application/problem+json media type and include a stable Headcode error code extension.

{
  "type": "https://docs.headcode.dev/errors/stations/not-found",
  "title": "Station Not Found",
  "status": 404,
  "detail": "No station found for identifier 'XYZ'.",
  "code": "HEADCODE.STATIONS.NOT_FOUND"
}

Top-level fields

Field	Required	Description
type	Yes	URI identifying the problem type. Headcode-specific problem types resolve to pages in this catalogue.
title	Yes	Short human-readable summary of the problem type.
status	Yes	HTTP status code for this occurrence.
detail	Usually	Human-readable detail specific to this occurrence.
instance	No	URI identifying this specific occurrence, if available.
code	Yes	Stable Headcode error code intended for logging, support, and client handling.
errors	No	Additional granular error details, usually for invalid parameters, headers, or request bodies.

Error detail objects

Some problems include an errors array to identify specific request parts.

{
  "type": "https://docs.headcode.dev/errors/general/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more request parameters are invalid.",
  "code": "HEADCODE.GENERAL.BAD_REQUEST",
  "errors": [
    {
      "detail": "Both 'lat' and 'lng' must be provided together.",
      "parameter": "lat",
      "code": "HEADCODE.STATIONS.SEARCH.COORDINATE_PAIR_REQUIRED"
    }
  ]
}

Field	Required	Description
detail	Yes	Granular description of the specific issue.
pointer	No	JSON Pointer to a request body property.
parameter	No	Query or path parameter that caused the issue.
header	No	Header that caused the issue.
code	No	Additional provider-specific code for the error context.

Catalogue

General

• Bad Request
• Unauthorized
• Not Found
• Method Not Allowed
• Internal Server Error
• Service Temporarily Unavailable

Stations

• Station Not Found

Services

• Service Not Found

Train orders

• Train Order Not Found

Locations

• Location Not Found

Disruptions

• Disruption Not Found

Operations

• Heartbeat Not Found