Skip to content

Error handling

The gateway and CLI distinguish transport errors, missing resources, invalid verification, and optional proof-layer results.

HTTP behavior

  • POST /v1/attestations returns 200 for a terminal job, 202 for pending/retryable work, and 429 when rate limited.
  • GET /v1/attestations/{hash} returns 404 when no job exists.
  • GET /v1/bundle/{hash} returns 404 when the attestation is absent or has no confirmed signed attestation.
  • GET /v1/proof/{hash} returns 404 when the attestation is not confirmed or not yet batched.
  • GET /v1/anchors/{hash} returns 404 for an unknown attestation, but 200 with [] when it is known and not batched.
  • The latest STH and historical STH routes return 404 when the requested checkpoint does not exist. Consistency requires first >= 1, second >= first, and both published STH sizes.
  • POST /v1/verify returns 200 even when its response has valid: false. Its opinion is not an authoritative local verification result.

Malformed hashes, malformed JSON, or wrong-length hex values are rejected by the relevant route. Hashes in API examples use lowercase hex without 0x; the CLI's decoder also accepts uppercase input and canonicalizes output.

CLI behavior

verify in text mode prints INVALID and exits non-zero when local threshold verification fails. With --output json, it reports the same verification failure as "valid": false but exits successfully; scripts must inspect the JSON field rather than relying only on the exit status. verify-proof exits non-zero for invalid home configuration, an invalid home threshold signature, malformed input, or missing required offline configuration. Invalid optional batch or cross-anchor layers are returned in a successful result with lower verification status instead of being treated as home-signature failures.

For anchors, the CLI intentionally maps a gateway 404 to an empty display. Do not interpret [] from that command as proof that the hash is known or that no anchor provider has a record. For status, an unknown hash remains an error.

Verification limits

Basic/VALID establishes only that the supplied configuration verifies the required signed digest. Batched adds a verified Merkle inclusion. Federated adds verified peer cross-anchors meeting policy. External-anchor objects are reported as present, not independently verified. None of these outcomes proves content authenticity, ownership, confidentiality, globally agreed time, or continued provider availability.