error.type, not the human-readable message. The message can be
reworded. The type and its structured fields are the wire contract.
A typed route and typed error do not prove that the capability is available.
Support also depends on audience, stability, topology, prerequisites, and
live evidence. Check capability status when an
error indicates an unavailable runtime or provider lane.
Namespaces
Internal failures return an incident reference rather than stack or
credential-bearing context.
Error registry
This table gives the complete error vocabulary’s default HTTP status and retryability. Each public operation declares its own error responses in the API reference. Use that operation’s declared responses when handling an HTTP request; a registry entry alone does not declare a response for an operation. The vocabulary also retains lifecycle and diagnostic codes that no current public operation declares as a typed HTTP response. For example,runtime.lease_lost, runtime.harness_failed, and retention.zdr_unsupported
are registry entries, not additional quickstart request errors. A code in a
Session outcome or diagnostic record does not give that record an HTTP status
or authorize repeating its provider effect.
“Yes” means the same idempotent Checkfu request is transport-safe to retry
according to the typed error contract. It does not mean an external provider
effect is known not to have happened.
Authorization availability
auth.authorization_unavailable means Checkfu could not evaluate authorization.
It returns HTTP 503 with the fixed message “Authorization could not be evaluated.
Retry the same request.” The public error does not expose the underlying store,
credential, policy, or diagnostic cause. Retry the same idempotent request after
authorization becomes available; do not replace its idempotency key.
This differs from an invalid credential (auth.invalid_key) and a settled deny
(policy.denied). An unavailable Memory content backend retains its distinct
memory.backend_unavailable error. A retryable authorization error does not, by
itself, prove that an external provider effect did not occur.
Principal request admission
auth.request_admission_unavailable (HTTP 503, retryable) means the Principal MCP
request-rate admission could not be evaluated. Retry the same request. The response
contains no binding, bucket, identity, or underlying failure details.
Authenticated Principal MCP requests share an edge-local limit of 120 requests per
60 seconds for each Workspace and Principal. Credential rotation retains the same
bucket. Exhaustion returns budget.exceeded (HTTP 429) with Retry-After: 60.
Authority and revocation checks remain independent; admission grants no permission
or spending authority. Trusted-source pre-authentication protection is not installed.
Settled decisions
These errors require a change in authority or configuration, not blind retry:validation.range_too_large is not a truncated success. The typed read refused
because the bounded range cannot be decoded under its current limit.
Wire version skew
Every general REST request carries a datedCheckfu-Version header, and every response
to a supported version echoes it. When a client sends a version the server does
not serve, the server answers validation.malformed and names the versions it
accepts. The refusal may advertise the server’s supported version in its response
header; that is not acceptance of the version the request sent. The TypeScript
SDK pins its version as WIRE_VERSION and
reports this case through isWireVersionUnsupportedError(error), with a message
that names the version it sent. Retrying cannot fix it: update the SDK or CLI to a
release that matches the server. checkfu doctor reports the same mismatch for the CLI.
Settled Managed Tool outcomes
runtime.managed_tool_failed and runtime.managed_tool_canceled report the
original call’s settled terminal outcome. The Session receives a masked error;
provider diagnostics remain private. These outcomes do not authorize a new
purchase or an automatic provider retry. Inspect the original Session event log
and Usage for execution and accounting facts.
Transient failures
For a retryable type, use exponential backoff and jitter and preserve the same idempotency key and request body when the route supports them.validation.idempotency_in_progress means another request with the same key is
still running. Retry the identical request. Do not generate a new key merely to
bypass the in-progress result.
runtime.observation_gap means execution evidence arrived out of order. Repeat
the same observation write; do not synthesize the missing provider event.
runtime.provider_host_unavailable means the provider webhook runtime is
unavailable. This includes a deployment without a configured provider catalog
and an unreachable configured host. A catalog failure does not prove a provider
request was sent. A lifecycle request may already have changed the provider
before its response was lost. Reconcile the same original request, preserving
its idempotency key when one was used, rather than dispatching a replacement.
runtime.provisioning_suspended means the current runtime lane entered a
cooldown after repeated provisioning failures. It is an availability result,
not evidence that a different unqualified provider is safe to select.
Indeterminate external effects
A timeout, gateway failure, lost lease, or provider error can occur after an external system accepted a request. In that case:- read the Session event log and Audit disposition;
- use the provider’s admitted lookup or idempotency mechanism when available;
- preserve the original operation identity; and
- leave the effect indeterminate until reconciliation establishes the result.
CLI exit codes
The CLI maps HTTP and domain failure classes to stable process exits:130 and 143 represent SIGINT and SIGTERM. checkfu session chat also
uses 130 when the remote Session is canceled. Read the Session event log for
execution truth; HTTP failure classes and chat turn outcomes are separate exits.
Chat outcome exits
After a dispatched turn reaches its Session boundary,checkfu session chat
returns the following process exit:
Exhausted retries fail the chat turn even though the Session remains addressable.
A custom tool request still waits for its result before chat finishes.