Errors and Retries
Errors and Retries
Document verified error contracts and client retry guidance.
Status: Partial implementation reference — Code-confirmed; operational validation pending
Last reviewed: 2026-10-21
Scope
Error representations, failure categories, retry eligibility and recovery requirements. The source-confirmed baseline below covers part of this scope; remaining operational details are unknown.
Current implementation baseline
Error contracts vary by route and representation: structured error objects, flat OAuth errors, text and bodyless responses coexist. HEAD has no response body. Preserve status, headers and original body instead of assuming a universal envelope.
Ingress distinguishes rejected credentials (401) from failed identity verification (502). First-write onboarding returns 428; WRITE_FENCE=true returns 503 with Retry-After. Relationship body and message/payload/event limits are separate; see the payload contract.
Checked writes use HTTP 412 for target precondition failures. corpus_identity_mismatch means the authoritative logical corpus differs from X-Expected-Corpus-Id; history_lineage_mismatch means the authoritative history generation differs from X-Expected-Corpus-Lineage. Both are permanent for that request target: retain the original operation token and payload, apply no automatic retry or endpoint substitution, and resolve the intended target explicitly. The response includes authoritative X-Corpus-Id and X-Corpus-Lineage. HTTP 503 lineage_unavailable instead means no authoritative identity can safely be established and requires operator recovery.
The same 412 codes apply to identity-checked SSE before HTTP 200 or any event is emitted. Retain the full prior checkpoint and distinguish this response from an ordinary disconnect: a disconnect may reconnect with the same expected identity and numeric cursor, while an identity mismatch requires an explicit target or recovery decision. Never replace the stored checkpoint with the mismatching response or silently retry it against another endpoint.
On an uncertain write outcome, retain the same operation token and identical payload. The SDK transport retries eligible safe reads, excluding operation-token acquisition and SSE; it does not automatically retry writes. Evidence: Ingress auth, Ingress router and SDK limitations.
