Errors

The single error shape used across the API, the status code table, and the codes worth knowing in advance.

Every error, on every endpoint, uses one shape:

{"error":"..."}

Some errors add a machine-readable code alongside error, for the cases where a caller needs to branch on the failure rather than just log it. Where a code exists, it is documented below; where it does not, match on the status code and treat error as a human-readable string, not a stable identifier.

Status codes

Code	Meaning
200	Success.
400	Malformed request: a bad body, a bad parameter, or freshness values (`nonce`, `issuedAt`, `expiresAt`) that fail the node's own checks.
402	No credits remaining on the key's account. Carries `code: "no_credits"`.
403	The organisation behind the key is suspended. Carries `code: "suspended"`.
404	The requested resource does not exist, or the endpoint is unconditionally unavailable for the given parameters.
409	Verify quorum: no digest reached the configured threshold.
422	Verification failed, or no verifier is registered for the credential's declared status type.
429	Rate limit exceeded. See Rate limits.
500	Signing the response failed on Attestra's side.
501	The target chain does not implement the capability the endpoint needs.
502	A read or write against a target chain failed, or its outcome could not be confirmed.

402 and 403 in full

{"error":"no credits remaining","code":"no_credits"}

{"error":"this organisation is suspended","code":"suspended"}

Why 404, not 403, for someone else's resource

A lookup against a resource that belongs to another organisation returns 404, not 403. A 403 would confirm the resource exists and is simply off limits, which is itself a small information leak. 404 gives nothing away either way.

Codes that surprise people

A few status codes carry meaning that is not obvious from the code alone. Each is explained in full on its endpoint page; this is the short version.

422 on Verify means the presentation failed verification: a bad holder signature, a tampered claim, or a revoked credential. It also covers a credential whose credentialStatus.type has no registered verifier; there is no separate code for "unrecognised type" versus "failed check."
501 on Verify quorum means the node you called is not configured as a collector: it has no peer list to fan the request out to. 501 on Attestation means the target chain does not implement read-back at all.
502 on Attestation means the read failed. It deliberately does not mean the record is absent: a failed read and a genuinely missing record are indistinguishable at that seam, so the endpoint uses this code instead of asserting absence.
502 on Push means the write failed or its outcome could not be confirmed. Importantly, it does not mean the transaction failed to send: the transaction may already be broadcast, pending, or even mined and reverted. See the Push page before retrying a 502.
404 on Status for ?chain=ethr is unconditional: every lookup against Ethereum through this endpoint returns 404, regardless of whether the credential exists. It does not mean the credential is missing.

5xx responses are not billed

A 5xx status is a failure on Attestra's side, and it is not billed. See Credits and billing for how the credit ledger handles this.