Contract v1 · generated reference

Error catalogue

Stable domain codes with explicit retry and recovery decisions.

Unknown errors must fail closed and use the server-error path. Do not map an unrecognized response to success or silently retry a consequential command.

Backend error codes and recovery guidance
Code	Recovery
`UNAUTHENTICATED`	Obtain or refresh the approved Firebase session, then retry only a safe request.
`PERMISSION_DENIED`	Do not retry unchanged; confirm role, membership and resource ownership.
`NOT_FOUND`	Return to the collection or previous safe step; do not invent the missing resource.
`CONFLICT`	Reload authoritative state, reconcile the version and ask the user to confirm a new intent.
`UNAVAILABLE`	Use bounded backoff, surface degraded state and consult service status.
`INVALID_ARGUMENT`	Correct the linked request fields before resubmitting.
`NOT_IMPLEMENTED`	Stop; the capability is not available on this transport/version.
`RATE_LIMITED`	Wait for the returned retry-after interval; do not fan out retries.
`EXPIRED`	Refresh the credential, quote, hold or session before a new request.
`STEP_UP_REQUIRED`	Complete recent-authentication step-up, then create a fresh authorized request.
`COMMERCIAL_AUTHORITY_PENDING`	Do not imply a booking or payment succeeded; wait for ratified authority.

Common integration contract

Sandbox and Production are isolated

Run examples only in a governed sandbox or local emulator. Sandbox identities, App Check tokens, payment fixtures and data do not grant Production access. The typed ports do not ratify a public numeric quota; enforcement may be stricter. Honor RATE_LIMITED and the server's retry-after value.

Authentication and authorization

Firebase Auth proves identity. App Check proves the approved app where a callable requires it. Roles, organization membership, requester identity and resource ownership are derived and rechecked by the server.

Authentication guide

Errors and recovery

Stable error codes distinguish validation, denial, conflict, expiry, authority pending, rate limiting and temporary unavailability. Never infer success from an HTTP redirect or a browser state.

Error catalogue

Idempotency, concurrency and retry

Reuse an idempotency key only for an identical retry. A new intent needs a new key. Preserve version preconditions and reload after a conflict.

Retry guidance

Changes and escalation

Check compatibility before adopting a new contract version. Review the changelog, service status and support guidance before retrying a persistent failure.

Changelog Service status Developer support

Common failure families
Family	Client decision
Authentication / authorization	Refresh or step up only when instructed; do not retry a denial unchanged.
Validation / conflict / expiry	Correct or reload state, then obtain confirmation for a new intent.
Rate limited / unavailable	Honor retry-after and use bounded backoff; inspect service status.
Unknown / server	Fail closed and escalate with a privacy-safe correlation id.

Executable network examples are published only when the exact wire schema is producer-proven. Check the selected operation's example-availability status; an unresolved schema is a release blocker, not permission to guess.

Verified examples and local-only recovery snippets