Registry Evidence errors and problems reference

Look up a problem response from Registry Evidence (Evidence) and decide what your relying party does next. Evidence returns RFC 9457 problem details as application/problem+json, under the frozen contract problem-contract.yaml.

Read a problem response

Every problem body has exactly six members: type, title, status, detail, code, and traceId. type is https://id.registrystack.org/problems/registry-evidence/ followed by the code with each . replaced by /. detail is static, value-free text chosen by the code alone: it never carries a selector, token, source value, or internal failure category.

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

Problem codes

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	Read GET /v1/evidence-definitions and send a selector profile it lists, with values the Source’s inputs schema accepts. No source was contacted.
auth.invalid-credential	401	Bearer access token is invalid	bearer access token validation failed	Send one valid Bearer access token. The response carries WWW-Authenticate: Bearer realm="registry-evidence".
evidence.denied	403	Evidence request is not permitted	the Evidence request is not permitted	Ask the operator for a grant that covers the requirement, purpose, and selector profile. The response does not say which condition failed.
resource.not-found	404	Requested resource was not found	the requested resource was not found	Check the route and HTTP method.
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 a cause or retry blindly. Retry only after the request inputs or the source’s records may have changed.
evidence.rate-limited	429	Evidence request rate is exhausted	the Evidence request rate is exhausted	Wait the one second Retry-After: 1 states, then retry.
source.unavailable	503	Authoritative source is unavailable	the authoritative source is unavailable	Retry with backoff, or contact the source operator. A selector value the Source places in a request path segment it cannot occupy (empty, . or .., or containing /, \, %, or a control character) also answers this problem, and a retry does not help: change the value.
service.unavailable	503	Service is unavailable	the request could not be served	Retry with backoff, or contact the Evidence operator.

evidence.denied never appears without its audit record: when Evidence cannot append the authorization-refusal audit event, it returns service.unavailable instead. A requirement that does not exist and one you are not authorized for are indistinguishable to you, and so are the reasons behind evidence.unavailable.

Client error kinds

The Evidence clients map a problem onto one error kind, so your code catches the kind and reads the problem code from the error’s code. Python raises the exception in the table; Node throws EvidenceClientError with kind set to the first column. The full contract is in the Evidence error contract.

Kind	Problem codes	Python
denied	auth.invalid-credential, evidence.denied, evidence.rate-limited	DeniedError
not-available	evidence.unavailable	NotAvailableError
invalid-request	evidence.invalid-request, request.selector-invalid, resource.not-found, format.unsupported	InvalidRequestError
unavailable	source.unavailable, service.unavailable	UnavailableError

An HTTP 429 response may set the retry delay (retry_after_seconds in Python, retryAfterSeconds in Node). Classification uses the code, HTTP status, type URI, and trace correlation. The clients discard response-authored title and detail text. A malformed problem, a registered code at the wrong status, or broken correlation becomes protocol.

A valid unknown code follows its HTTP status: 401, 403, and 429 are denied; 422 is not-available; other 4xx responses are invalid-request; 5xx responses are unavailable.

Request batches

POST /v1/evidence/batch uses the same problem contract for a failure that aborts the whole batch. Inside a successful response, an item that could not be produced is the result evidence-not-available, not the evidence.unavailable problem.

Public check

POST /v1/public-check is experimental and uses the same problem shape and codes. It adds no code.

• evidence.invalid-request (400): the Content-Type is not exactly application/json, the body is larger than the route accepts, the body is not JSON with exactly the string members documentNumber and checkCode, or checkCode is not 24 characters of A to Z and 2 to 7. A lowercase checkCode is accepted: the server uppercases it before the comparison.
• request.selector-invalid (400): documentNumber does not fit the number format the route accepts, or the Source’s inputs schema refuses it.
• resource.not-found (404): no certificate matches. A wrong number, a wrong code, and a record with no stored code give the same answer, so a caller cannot tell which part was wrong.
• source.unavailable (503): the registry could not be read. A documentNumber that passes the selector profile and the inputs schema but that the Source binds to a path segment it cannot occupy (for example a/b or ..) answers the same problem, after the access-attempt audit entry and before any registry request. The check code is compared only after the Source returns a record, so every Source failure before the comparison answers this problem. Retry later.
• service.unavailable (503): Evidence could not complete the check. Retry later.

Both 400 problems come before any audit write and any registry read.

Next

Registry Evidence API