Evidence Gateway errors and problems reference

Evidence Gateway returns RFC 9457 problem details as application/problem+json. The frozen source contract is products/evidence/contracts/problem-contract.yaml. The generated schema and OpenAPI documents are reproduced from the runtime and must not be edited by hand.

Read a problem response

Every problem body has exactly these six members: type, title, status, detail, code, and traceId. detail is static and value-free. It never includes a selector, token, source value, audit operation, or internal failure category. type always begins with https://id.registrystack.org/problems/registry-evidence/.

{
  "type": "https://id.registrystack.org/problems/registry-evidence/evidence/unavailable",
  "title": "Evidence could not be produced",
  "status": 422,
  "detail": "evidence could not be produced for this request",
  "code": "evidence.unavailable",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Every response carries a W3C traceparent header. For a problem response, its trace identifier is the same value as traceId. Evidence Gateway accepts a valid inbound trace identifier for correlation or mints one, but does not echo tracestate. The trace identifier is not the internal server-minted audit operation identifier. All responses use Cache-Control: no-store.

Problem code matrix

Code	Status	Title	Detail	Recovery
evidence.invalid_request	400	Evidence request is invalid	the Evidence request is invalid	Correct the request body or headers.
request.selector_invalid	400	Selector is invalid	selector does not match an available request profile	Fetch authenticated definitions and use an available selector profile. A value the deployment places in a source request path must also fit one path segment: not empty, not . or .., and free of /, \, %, and control characters. This code is returned before any source is contacted, never as source.unavailable.
auth.invalid_credential	401	Bearer access token is invalid	bearer access token validation failed	Supply one valid Bearer access token. The response also carries WWW-Authenticate: Bearer realm="registry-evidence".
evidence.denied	403	Evidence request is not permitted	the Evidence request is not permitted	Obtain an appropriate entitlement. The response does not identify the failed authorization condition.
resource.not_found	404	Requested resource was not found	the requested resource was not found	Check the route and HTTP method. Unknown paths and unsupported methods use this code.
format.unsupported	406	Requested format is not supported	the requested format is not supported	Send one exact supported Accept value.
evidence.unavailable	422	Evidence could not be produced	evidence could not be produced for this request	Do not infer the cause or retry blindly. Retry after request inputs or authoritative source state may have changed, or follow operator guidance. The service does not disclose the unavailable class.
evidence.rate_limited	429	Evidence request rate is exhausted	the Evidence request rate is exhausted	Wait one second, as stated in Retry-After: 1, then retry.
source.unavailable	503	Authoritative source is unavailable	the authoritative source is unavailable	Retry with backoff or contact the source operator.
service.unavailable	503	Service is unavailable	the request could not be served	Retry with backoff or contact the Evidence Gateway operator.

Retry-After is present only on 429 responses.

Request batches

POST /v1/evidence/batch uses the same outer problem contract for any failure that aborts the batch. Its successful envelope keeps the item discriminator evidence_not_available unchanged for the closed unavailable outcome. It is not the outer evidence.unavailable problem code.

Source

The code, status, title, detail, headers, and batch semantics are transcribed from products/evidence/contracts/problem-contract.yaml and the generated runtime artifacts. The Recovery column is operational guidance. The complete generated route mapping is in products/evidence/generated/registry-evidence.openapi.json.