Error catalogue

The catalogue is closed: a failure carries one of these codes and no others. Branch on code, never on message — the code is stable, the sentence is not. How the envelope is shaped, and the four cases worth special handling, are on Errors.

retryable is derived from the error class and travels in the envelope. The column below is the class default; provider_error takes its retryability per instance, so for that one read the value you were sent rather than this table.

Code	HTTP	Retryable by default
budget_exceeded	402	no
code_run_failed	502	no
configuration_invalid	500	no
conflict	409	no
decryption_failed	500	no
forbidden	403	no
guardrail_blocked	422	no
idempotency_in_flight	409	yes
idempotency_key_mismatch	422	no
idempotency_key_reuse	422	no
invalid_transition	409	no
lease_lost	409	no
malformed_json	400	no
method_not_allowed	405	no
model_supplied_repository_scope	403	no
not_found	404	no
not_implemented	501	no
not_resumable	422	no
not_suspended	409	no
payload_too_large	413	no
plan_limit_exceeded	402	no
platform_error	500	no
provider_error	502	no
rate_limited	429	yes
resume_contract_mismatch	409	no
secret_missing	404	no
storage_unavailable	422	no
suspension_expired	409	no
template_render_failed	422	no
token_expired	401	no
token_type_mismatch	401	no
tool_results_mismatch	422	no
transient	503	yes
unauthenticated	401	no
unsupported_media_type	415	no
validation_failed	422	no
wait_timeout	504	yes
write_credential_in_sandbox	403	no