Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/llms.txt
Full corpus: https://docs.registrystack.org/llms-full.txt

# Evidence Gateway errors and problems reference

> Evidence Gateway problem responses, their stable codes, and safe recovery actions.

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/`.

```json
{
  "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. |
| `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 retry an unchanged request. The service does not disclose whether the cause was no match, ambiguity, a missing fact, or unresolved derivation input. |
| `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

This page transcribes `products/evidence/contracts/problem-contract.yaml`.
The complete generated route mapping is in
`products/evidence/generated/registry-evidence.openapi.json`.