Errors

Every handled error returns a consistent JSON envelope with an HTTP status code, a stable machine-readable code, and a human-readable message.

{
  "error": {
    "code": "validation_error",
    "message": "One or more request fields are invalid.",
    "request_id": "9f4c1d2e-7b3a-4f7e-9c1d-2e7b3a4f7e9c",
    "severity": "error",
    "details": [
      {
        "code": "greater_than_equal",
        "message": "Input should be greater than or equal to 0",
        "target": "lines.0.amount",
        "severity": "error"
      }
    ]
  }
}

Error codes

Request IDs

Every response carries an X-Request-Id header, and handled errors echo the same id as error.request_id. Include it when contacting support so we can locate the exact request.

Service-provider authorization errors

Provider administration requires a provider credential. Taxpayer-data calls additionally require X-ITMS-Client-Ref (recommended) or the numeric engagement ID in X-ITMS-Client-Id. If both are present, they must select the same client. Authorization failures do not disclose whether another provider's client exists. See the service-provider portfolio guide for the full context model.

Validation errors

Request-body validation failures (missing fields, malformed values) return HTTP 422 with code validation_error in the standard envelope. Inspect error.details for stable field targets such as lines.0.amount. Submitted values are not echoed in validation errors.

Unhandled errors

Unexpected server errors return HTTP 500 with code internal_error in the same envelope and a request id. Stack traces and internal details are never returned to API consumers.

Duplicate transactions

Reusing a transaction code returns HTTP 409 duplicate_transaction without modifying the original — see Transaction lifecycle for the full duplicate and retry semantics.