Veridion Disclosure API · problems

Every error the API can return.

When a request cannot be answered, the API returns an RFC 9457 problem document with a stable code, a type that resolves to the entry below, and a request_id equal to the X-Request-ID header. 17 problems are defined for version 1.3.5. A route cannot emit a code that is not on this page; the build fails.

{
  "type": "https://www.veridionmarkets.com/data-api/problems/rate_limited",
  "code": "rate_limited",
  "title": "Free-tier request budget exceeded.",
  "status": 429,
  "detail": "The free tier allows 60 requests per hour per IP. ...",
  "request_id": "6f1c…"
}

HTTP 400

unknown_query_parametercaller changes the request

One or more query parameters are not supported.

The request named a query parameter this operation does not define. The API refuses the request instead of ignoring the parameter, because a silently ignored filter returns the wrong rows under a 200.

Fix the request; do not retry as sent.

invalid_requestcaller changes the request

One or more query parameters are invalid.

A known parameter carried a value outside its contract: a malformed date, a limit above the tier's cap, an unknown chamber, a badly formed identifier.

Fix the request; do not retry as sent.

invalid_disclosure_idcaller changes the request

The disclosure identifier is invalid.

The path segment is not shaped like a permanent v1 disclosure_id. This is a syntax check; it says nothing about whether such a record exists.

Fix the request; do not retry as sent.

invalid_cursorcaller changes the request

The cursor is not one this API issued for this query.

Cursors are signed and carry the query they belong to. A cursor that fails its signature, or that was issued for a different filter set or pull mode, is refused rather than applied to the wrong query.

Restart from page one without a cursor.

temporal_history_unavailablecaller changes the request

The requested point in time predates retained payload history.

as_of or updated_since is earlier than coverage.point_in_time_floor. The API returns a typed refusal instead of an empty page, because an empty page would read as "nothing happened" when the truth is "we cannot say".

Fix the request; do not retry as sent.

HTTP 401

unauthorizedcaller changes the request

A valid API key is required.

An Authorization header was present and did not carry a valid key. The free tier needs no key: omit the header entirely to use it.

Fix the request; do not retry as sent.

HTTP 403

insufficient_scopecaller changes the request

This key is not authorized for this Disclosure API endpoint.

The key is valid but its scopes do not include this operation.

Fix the request; do not retry as sent.

HTTP 404

disclosure_not_foundcaller changes the request

No disclosure exists for this permanent identifier.

The permanent disclosure_id namespace was searched across active and withdrawn records and nothing matched. Withdrawn identifiers still resolve with their reason, so a 404 means the identifier was never issued.

Fix the request; do not retry as sent.

no_snapshot_yetVeridion side

No bulk snapshot has been generated yet.

The bulk export is produced daily. This is a pipeline state, not an authorization failure.

Retry later; the request was sound. Every 503 carries Retry-After with the minimum wait.

HTTP 409

cursor_snapshot_unavailableVeridion side

The cursor snapshot is no longer available.

Every cursor pins the snapshot it was issued against so later writes cannot shift a page mid-pull. That snapshot is no longer retained. The API refuses to continue the pull against a different snapshot.

Restart from page one without a cursor.

HTTP 429

rate_limitedcaller changes the request

Free-tier request budget exceeded.

The anonymous budget stated in X-RateLimit-Policy was used up for this address. Retry-After says how long until the window opens.

Retry after the Retry-After header elapses.

HTTP 503

warehouse_unavailableVeridion side

The disclosure warehouse is temporarily unavailable.

The read behind this response did not complete within its budget. The API returns no rows rather than a partial page, and a 503 is never cached.

Retry later; the request was sound. Every 503 carries Retry-After with the minimum wait.

api_auth_unavailableVeridion side

API authentication is temporarily unavailable.

The key could not be checked because the authentication store did not answer. This is not a judgement on the key.

Retry later; the request was sound. Every 503 carries Retry-After with the minimum wait.

api_usage_meter_unavailableVeridion side

Evaluator usage evidence could not be recorded.

Evaluator-tier requests are metered in the database as evidence of use. When the meter cannot record, the API serves nothing rather than an unmetered response.

Retry later; the request was sound. Every 503 carries Retry-After with the minimum wait.

contract_validation_failedVeridion side

A stored disclosure does not satisfy the public contract.

A row read from the warehouse failed the published schema at serve time. The API refuses to serve a row that does not match its own contract. This is a Veridion defect, not a request problem.

Retry later; the request was sound. Every 503 carries Retry-After with the minimum wait.

temporal_capability_unavailableVeridion side

Point-in-time history is temporarily unavailable.

as_of or updated_since needs the temporal read model and it did not answer. The detail field carries the measured reason.

Retry later; the request was sound. Every 503 carries Retry-After with the minimum wait.

signing_failedVeridion side

The snapshot exists but a download URL could not be signed.

The bulk snapshot is present; the short-lived download link could not be produced.

Retry later; the request was sound. Every 503 carries Retry-After with the minimum wait.

Problem documents are returned by every v1 route except where the OpenAPI document declares a legacy error body for an operation. Questions with a request id go to support@veridionmarkets.com.