Errors and recovery
Read the contract for the failing surface
Section titled “Read the contract for the failing surface”| Surface | Presentation | Recovery |
|---|---|---|
| Gateway HTTP | HTTP status and structured envelope; fields depend on the operation | Preserve operation/idempotency identity; follow supplied next actions and retry safety |
| CLI | JSON result/error and process exit status | Read stderr and complete JSON; pending verification is not verified deployment |
| SDK | Typed errors and type guards | Narrow with exported guards; fields differ by error kind |
| MCP | Tool result/error content | Inspect structured content and the tool schema; it is not a CLI process |
| Application runtime/Core | Runtime-specific diagnostic or typed exception | Consult the owning runtime and request context |
No universal envelope promises status, suggestedFix or docs on every error. See CLI errors, SDK types and MCP recovery.
For deployment failures inspect run402 doctor --project prj_example and the returned operation’s next actions. Do not repeat an ambiguous mutation or a paid request with a new idempotency key. Unknown future codes remain data; preserve their original details.
Code destinations
Section titled “Code destinations”The catalog records owning source locations and pinned external contributions. A listed code is addressable, not a promise that every interface emits it.
ACCEPT_PAYMENT_TOO_MANY_FIELDS
ADMIN_SQL_CAPABILITY_GATE_FAILED
ADMIN_SQL_CHANNEL_UNCONFIGURED
ARCHIVE_ENTRY_TYPE_UNSUPPORTED
ARCHIVE_MEDIA_TYPE_UNSUPPORTED
ARCHIVE_UNSUPPORTED_REQUIRED_CAPABILITY
BUZZ_ADOPTION_CALLBACK_INVALID
BUZZ_ADOPTION_OFFER_INELIGIBLE
BUZZ_ADOPTION_OFFER_NOT_ACTIVE
BUZZ_ADOPTION_OFFERS_UNSUPPORTED
BUZZ_COMMUNITY_PROOF_UNSUPPORTED
BUZZ_ENROLLMENT_APPROVAL_REQUIRED
BUZZ_ENROLLMENT_SCOPE_UNSUPPORTED
CLIENT_DIAGNOSTIC_EVENT_INVALID
CLIENT_DIAGNOSTIC_RATE_LIMITED
CONTENT_ENCODING_NOT_SUPPORTED
DESIRED_RECIPIENTS_NOT_RECONCILED
EMAIL_BELONGS_TO_OTHER_PRINCIPAL
EMAIL_SEND_IDENTITY_REGISTRATION_FAILED
EPOCH_ROTATION_INCOMPLETE_ENROLLMENT
EPOCH_ROTATION_SELF_OPEN_UNPROVEN
EPOCH_ROTATION_WOULD_LEAVE_VAULT_UNCOVERED
EXECUTABLE_CONFIG_EVALUATION_FAILED
EXECUTABLE_CONFIG_INVALID_EXPORT
EXECUTABLE_CONFIG_TS_LOADER_UNAVAILABLE
EXPORT_CONSISTENCY_UNAVAILABLE
HANDOFF_CHECKPOINT_FETCH_FAILED
HANDOFF_REDEEM_WRITER_KEY_MISMATCH
IDEMPOTENCY_KEY_PAYER_REQUIRED
IDENTITY_LINK_ATTEMPTS_EXHAUSTED
IDENTITY_LINK_AUTHENTICATOR_CHANGED
IDENTITY_LINK_AUTHENTICATOR_MISMATCH
IDENTITY_LINK_CAPABILITY_UNAVAILABLE
IDENTITY_LINK_CHALLENGE_EXPIRED
IDENTITY_LINK_CHALLENGE_NOT_FOUND
IDENTITY_LINK_CROSS_BINDING_FAILED
IDENTITY_LINK_EOA_SIGNER_MISMATCH
IDENTITY_LINK_EOA_SIGNER_REQUIRED
IDENTITY_LINK_EVENT_INCOMPLETE
IDENTITY_LINK_EVENT_NOT_CANONICAL
IDENTITY_LINK_EVENT_SOURCE_REQUIRED
IDENTITY_LINK_EVENT_TAGS_NOT_ALLOWED
IDENTITY_LINK_INVALID_WALLET_SIGNATURE
IDENTITY_LINK_PRINCIPAL_CONFLICT
IDENTITY_LINK_PUBLIC_VISIBILITY_REQUIRED
IDENTITY_LINK_REQUIRES_AGENT_EOA
IDENTITY_LINK_REQUIRES_HUMAN_SESSION
IDENTITY_LINK_SECRET_INPUT_FORBIDDEN
IDENTITY_LINK_SUBJECT_CONFLICT
INBOUND_DOMAIN_ALREADY_ENABLED
INVITE_REDEEM_WRITER_KEY_MISMATCH
ISSUER_OUTSTANDING_CAP_REACHED
KEY_ROTATION_NOT_SELF_AUTHORIZABLE
LIGHTNING_RECEIVER_PROBE_FAILED
LIGHTNING_RECEIVER_UNAVAILABLE
LIGHTNING_TOPUP_AMOUNT_OUT_OF_BOUNDS
LIGHTNING_TOPUP_NOT_CONFIGURED
LIGHTNING_TOPUP_PROVIDER_UNAVAILABLE
LIGHTNING_WALLET_NOT_AVAILABLE
LIGHTNING_WALLET_STILL_MINTING
LOCAL_CREDENTIAL_CACHE_UNSUPPORTED
MAINTENANCE_CYCLE_RESTART_REQUIRED
MAINTENANCE_STAGE_LIMIT_EXCEEDED
MAX_EPOCH_ROTATION_ENVELOPES_EXCEEDED
ORGANIZATION_PURGE_IN_PROGRESS
ORGANIZATION_SELECTION_REQUIRED
PAYMENT_ATTEMPT_RECORD_INVALID
PAYMENT_AUTHORIZATION_LIFETIME_EXCEEDED
PAYMENT_CALLER_IDENTITY_NOT_ACTIVE
PAYMENT_INTENT_DESTINATION_CHANGED
PAYMENT_INVOICE_PROVISIONING_RETRY
PAYMENT_OPERATION_CONTRACT_CHANGED
PAYMENT_PREIMAGE_HASH_MISMATCH
PAYMENT_QUOTE_SOURCE_UNAVAILABLE
PAYMENT_SEMANTIC_HEADER_DUPLICATE
PAYMENT_SEMANTIC_HEADER_INVALID
PAYOUT_WALLET_TEMPO_UNVERIFIED
PIN_MANIFEST_STORAGE_INTEGRITY_FAILURE
PRINCIPAL_NOSTR_IDENTITY_ALREADY_LINKED
PROJECT_CREDENTIAL_PROJECT_MISMATCH
PROJECT_HAS_NON_REPO_RESOURCES
R402_ASTRO_ADAPTER_MANIFEST_MISSING
R402_ASTRO_ADAPTER_MANIFEST_VERSION_UNSUPPORTED
R402_ASTRO_DYNAMIC_IMAGE_UNSUPPORTED
R402_ASTRO_IMAGE_ASSET_MISSING
R402_ASTRO_IMAGE_ASSET_STRING_URL
R402_ASTRO_IMAGE_ASSET_WRONG_SHAPE
R402_ASTRO_IMAGE_CONFLICTING_CLASS_PROPS
R402_ASTRO_IMAGE_CONFLICTING_LOADING_PROPS
R402_ASTRO_IMAGE_HEIC_NO_TRANSCODE
R402_ASTRO_IMAGE_NON_IMAGE_ASSET
R402_ASTRO_IMAGE_RESERVED_DATA_ATTR
R402_ASTRO_IMAGE_SIZES_REQUIRED
R402_ASTRO_IMAGE_STRICT_DEGRADED
R402_ASTRO_IMAGE_WRONG_ENTRY_POINT
R402_ASTRO_MIDDLEWARE_UNSUPPORTED
R402_ASTRO_SDK_VERSION_TOO_OLD
R402_ASTRO_SERVER_ISLAND_UNSUPPORTED
R402_ASTRO_SESSIONS_UNSUPPORTED
R402_ASTRO_VERSION_UNSUPPORTED
R402_AUTH_AUTHZ_VERSION_PROHIBITED
R402_AUTH_BEARER_COOKIE_MISMATCH
R402_AUTH_COOKIE_ATTRIBUTES_INVALID
R402_AUTH_CSRF_ORIGIN_MISMATCH
R402_AUTH_EMAIL_CODE_EXHAUSTED
R402_AUTH_IDENTITY_LINK_CONFLICT
R402_AUTH_INSUFFICIENT_MEMBERSHIP
R402_AUTH_MEMBERSHIP_GATE_NOT_WIRED
R402_AUTH_OAUTH_BRIDGE_INVALID
R402_AUTH_PASSKEY_CHALLENGE_INVALID
R402_AUTH_REDUNDANT_USER_FILTER
R402_AUTH_RESERVED_EMAIL_DOMAIN
R402_AUTH_ROLE_GATE_NOT_CONFIGURED
R402_AUTH_SESSION_BRIDGE_UNVERIFIED
R402_AUTH_TENANT_SUBJECT_INVALID
R402_AUTH_TENANT_SUFFIX_REQUIRED
R402_BACKFILL_CHECKPOINT_CONFLICT
R402_BACKFILL_HEIC_TRANSCODE_FAILED
R402_BUNDLE_NATIVE_DEP_UNSUPPORTED
R402_CACHE_INVALIDATION_HOST_FORBIDDEN
R402_CACHE_INVALIDATION_HOST_REQUIRED
R402_DOCTOR_AUTH_SESSION_MINT_CAPABILITY_MISSING
R402_FUNCTION_RUN_INVALID_INPUT
R402_FUNCTION_RUN_MISSING_CONTEXT
R402_PAYMENT_FULFILLMENT_CONTEXT_EXPIRED
R402_PAYMENT_FULFILLMENT_DIRECTIVE_INVALID
R402_PAYMENT_FULFILLMENT_OUTSIDE_ROUTED_REQUEST
R402_PAYMENT_FULFILLMENT_RECEIPT_NOT_ENABLED
R402_PAYMENT_FULFILLMENT_UNSETTLED
R402_SDK_OUTSIDE_REQUEST_CONTEXT
RECIPIENT_LIGHTNING_RECEIVER_REQUIRED
RECIPIENT_PAYOUT_WALLET_TEMPO_REFUSED
RELINK_SOURCE_PAYOUT_WALLET_SELECTED
ROOM_INVITE_KEY_ALREADY_REDEEMED
ROOM_INVITE_REDEEM_REQUIRES_WALLET
RUN402_ASTRO_LEADING_SLASH_SRC
RUN402_ASTRO_MISSING_ASSET_REF
RUN402_ASTRO_MISSING_PROJECT_ID
RUN402_ASTRO_UNSUPPORTED_EXTENSION
RUN402_TARGET_ANON_KEY_REQUIRED
RUN402_TARGET_PROJECT_REQUIRED
RUN402_TARGET_SERVICE_KEY_REQUIRED
RUN402_WORKSPACE_LINK_CONFLICT
SNAPSHOT_AUTH_RESTORE_REQUIRES_PRINCIPAL
SNAPSHOT_KIND_NOT_DELETABLE_BY_SERVICE_KEY
STRIPE_ACCOUNT_ONBOARDING_INCOMPLETE
STRIPE_CHECKOUT_SESSION_NOT_FOUND
TENANT_MPP_SETTLEMENT_UNCERTAIN
TIER_PAYMENT_IDENTITY_REQUIRED
TRANSFER_FACILITATOR_UNAVAILABLE
TRANSFER_VAULT_BYO_UNSUPPORTED
TRANSFER_VAULT_HANDOVER_PENDING
TRANSFER_VAULT_HANDOVER_PRINCIPAL_MISMATCH
TRANSFER_VAULT_RECIPIENT_NOT_NOMINATED
TYPESCRIPT_FUNCTION_REQUIRES_BUNDLE
UNSUPPORTED_DEPLOY_MANIFEST_EXTENSION
UNSUPPORTED_EXECUTABLE_CONFIG_EXTENSION
VAULT_ACTIVATION_TOKEN_MISSING
VAULT_COMPACT_INSUFFICIENT_HEADROOM
VAULT_ENVELOPE_RECIPIENT_NOT_ELIGIBLE
VAULT_EXCLUDES_PATH_UNSUPPORTED
VAULT_IDENTITY_PROFILE_MISMATCH
VAULT_OVERRIDE_COMPLETION_MISMATCH
VAULT_OVERRIDE_COMPLETION_REFUSED
VAULT_PIN_MANIFEST_READ_UNSUPPORTED
VAULT_PROOF_OF_OPEN_PRINCIPAL_UNRESOLVED
VAULT_RECEIPT_ID_REUSED_DIFFERENT
WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS
WRITE_APPROVAL_BINDING_MISMATCH
WRITE_APPROVAL_CHALLENGE_INVALID
WRITE_APPROVAL_CP_SESSION_DEAD
WRITE_APPROVAL_SESSION_INVALID
X402_AMOUNT_EXCEEDS_FIRST_PARTY_CAP