Error codes

Every API error response includes a stable code string alongside the human-readable message. Match on the code, not the message.

Code	HTTP	Meaning / recovery
INVALID_SIGNATURE	400	Canonical bytes do not match the signature. Usually an SDK serialization mismatch, see FAQ.
NONCE_REPLAY	409	Submitted nonce ≤ highest known nonce for the signer. Fetch current and retry with +1.
EPOCH_MISMATCH	409	Signer is at a later epoch than the transaction is using. Rebuild with current epoch key.
DOMAIN_NOT_FOUND	404	Domain is not served by this node. Check SUPPORTED_DOMAINS configuration.
QUID_NOT_FOUND	404	Subject or signer quid is not registered.
TRUST_PATH_NOT_FOUND	404	No trust path within the configured depth. Raise maxDepth or declare a more direct edge.
GUARDIAN_QUORUM_INSUFFICIENT	409	Recovery init signed by fewer than M of N guardians.
GUARDIAN_NOT_CONSENTED	409	A signing guardian has not submitted their GuardianSetUpdate consent.
RECOVERY_IN_FLIGHT	409	A recovery is already in the time-lock window; veto or wait for commit.
RECOVERY_VETOED	410	The recovery has been vetoed by the subject during time-lock.
PAYLOAD_TOO_LARGE	413	Event payload exceeds 64 KB inline limit. Attach via IPFS CID.
RATE_LIMITED	429	Exceeded RATE_LIMIT_PER_MINUTE. Back off and retry.
NODE_AUTH_REQUIRED	401	Inter-node endpoint called without a valid HMAC when REQUIRE_NODE_AUTH=true.
BLOCK_ORPHANED	410	Your anchor referenced a block that was since orphaned by tiering.
FORK_NOT_ACTIVE	409	Feature requires a QDP that is not yet active at this block height.

Operational tips

• Treat INVALID_SIGNATURE as a programming bug, not a transient error, don’t retry blindly.
• Treat NONCE_REPLAY and EPOCH_MISMATCH as recoverable: fetch the signer’s current state, rebuild, resubmit.
• Treat RATE_LIMITED with jitter + exponential back-off up to a cap.
• When a GUARDIAN_* flow returns an error, prefer inspecting /api/v2/guardians/sets/{quidId} for the current state rather than guessing.

Debug utilities

• GET /api/info, node version, feature flags, supported domains.
• GET /metrics, Prometheus. Look for quidnug_tx_rejected_total{code=…} counters broken down by the same codes as above.

For cross-SDK signature interop issues, run the harness at tests/interop/ make produce verify emits and verifies reference vectors.