Error codes

Every refusal from the owner-api carries one stable code. On the always-detailed routes (most routes added from 1.4.0 on; each code's page says which routes send it), and on every other route when the request sends Dynamo-Error-Detail: 1, the body adds an errorDetail object:

{
  "errorDetail": {
    "type": "halted",
    "code": "cap",
    "message": "…",
    "param": null,
    "doc_url": "…/errors/cap.md",
    "headroom": {
      "remainingCapUnits": "…",
      "remainingNetworkUnits": "…"
    },
    "fix": "…"
  }
}

doc_url points at the page below; set CORE_DOCS_BASE_URL to serve them from your own docs host. Messages name ids, units and reasons only, never request bodies or credentials. A refused request bills nothing.

Common questions about refusals, caps, refunds and keys are answered in the FAQ.

CodeHTTPMeaning
revoked409The stream was revoked
stopped409The budget was stopped
frozen409The stream is frozen
mandate_amended409An amendment left this stream outside its mandate
mandate_payee409The payee is not allowed
mandate_assurance409The payee identity level is below the mandate minimum
mandate_verification409The agent's verification level is below the mandate minimum, or no provider can attest it
mandate_window409The mandate is outside its time window
funder_identity409The root funder's identity level is below the deployment minimum
session_signer_missing409No session signer is supplied for the payer's session key
session_signer_mismatch409The session signer's signature is not canonical or not the key's
session_signer_unavailable409The hosted tier takes no payer-supplied session signer
funding_adopt_only409The stablecoin mode only adopts budgets users open from their own wallets
adopt_refused409The on-chain budget does not match the prepared adoption
child_adopt_refused409The on-chain child does not match the prepared child adoption
hop_unsigned409The hop carries no signature by its delegator
hop_signature409The hop signature does not cover this open
hop_delegator409The hop is signed by someone other than its delegator
hop_parent_signer409The parent agent's signer is not reachable here
hop_replay409The hop intent was already used
hop_consent409A consent-attributed hop outside a top-up's root
hop_mandate_mismatch409The hop signs a different child mandate
non_canonical_path400The request path is not in canonical form
offer_unsigned409The hop carries no signed payee offer
offer_signature409The payee offer is not signed by the payee
offer_shape409The payee offer is malformed
offer_category409The payee does not offer this category
offer_expired409The payee offer is outside its validity window
offer_v1409This deployment accepts only v2 offers and quotes
offer_audience409The offer or quote was made for another deployment
offer_addressee409The offer or quote is addressed elsewhere
offer_lifetime409The offer or quote lives outside its bound
offer_revoked409The payee revoked this offer or quote
offer_revoke400The offer revocation is refused
tenant_rate_limited429This tenant's request rate is used up
key_scope403This API key cannot call that route
credential_scope403This scoped credential cannot call that route or object
key_binding_required400The SD-JWT link has no key-binding JWT
key_binding_challenge400The key-binding JWT does not answer a live challenge
conflict409The account or link already exists
proof_invalid400The identity proof does not verify
link_challenge400The link proof does not answer a live challenge
proof_unavailable503This deployment cannot check that proof type
quota_exceeded409This account's quota for a resource is reached
live_mode_gated409Live keys run Control Mode only for now
version_unknown400The deployment does not know this API version
version_unavailable404This route is newer than the pinned version
csrf403The dashboard session's CSRF token is missing or wrong
link_invalid400The emailed link is unknown, used or expired
tenancy_unavailable503The account's store or mail relay is unavailable
widget_origin_refused403This origin may not call the widget routes
token_missing401No browser token was presented
token_malformed401The browser token is not in the minted form
token_revoked401The browser token is revoked or unknown here
token_wrong_kind401The browser token is for another surface
token_signature_invalid401The browser token was altered
token_expired401The browser token has expired
owner_token_refused401Browser surfaces never accept the owner token
scope_insufficient403The widget token cannot approve or reject
client_keyed_hold409Approve this open from the client that opened it
end_user_budget_conflict409The budget already belongs to another end user
topup_card_mode_absent409The credit card rail is not configured here
topup_payee_not_routable409The payee has no connected account here
topup_payee_offer_required409The top-up needs the payee's signed offer
topup_payee_offer_invalid409The payee offer does not cover this top-up
topup_not_pending409The top-up already ran
topup_authentication_required402The card needs 3-D Secure, which the preview does not support
topup_declined402The credit card authorization was declined
topup_funding_failed402The top-up did not complete
test_fixture_money_mode409Test service nodes run on Control Mode only
test_fixture_not_fixture409The stream does not pay a test service node
test_fixture_refused409The refuse fixture refused the work
mandate_limit409The request exceeds a mandate limit
approval_required409The action is waiting for approval
anomaly409The stream exceeded its anomaly envelope
sla409An objective SLA threshold was breached
terms_unavailable409Terms are not offered on this deployment
terms_offer_invalid409The terms offer is not usable
terms_offer_expired409The terms offer is outside its validity window
terms_offer_version400Registering terms offers needs Dynamo-Version 1.9.0 (R-414)
terms_catalogue_mismatch409The offer was made against another catalogue
terms_not_in_catalogue409A term is not in the catalogue
terms_not_accepted409The payer did not accept these terms
terms_signer409The breach signers are not usable
terms_holdback409The holdback is shorter than the term window
breach_no_terms409The stream carries no accepted terms
breach_report_invalid409The breach report is malformed
breach_signature409The breach report signature does not verify
breach_signer409The report's signer was not opted into
breach_fingerprint409The report is for other terms
breach_term409The report names a term the stream does not carry
breach_not_breached409The measured value meets the term
breach_time409The report's times do not fit
breach_stale409The breach report is too old
budget_expired409The contract v2 budget has expired
breach_conflict409Another breach time is already recorded
breach_unmatched409No accepted breach report
breach_refund_window409The holdback window has passed
refund_no_terms409The stream has no declared or accepted terms
refund_unattested409No attested break-point at that instant
budget_closed409The budget is closed
exposure409The unsettled exposure limit is reached
checkpoint_pending409The stream waits for its next checkpoint
settlement_pending409The voucher waits for the chain's clock to pass its signing time
reservation_expired409A late confirm no longer fits after the hold expired
task_quote_invalid409The task quote is not usable
task_quote_expired409The task quote is outside its validity window
task_quote_signature409The task quote is not signed by its payee
task_not_accepted409The funder did not accept this quote
task_window_bounds409The acceptance window is out of bounds
task_deliver_bounds409The delivery deadline is out of bounds
task_standards_unavailable409Declared standards need a terms catalogue
task_stream_mismatch409The stream does not fund this quote
task_rate_too_low409The stream's rate cannot reach the cap inside the window
task_rail_unsupported409Tasks do not run on this rail
task_horizon_unknown409The funded horizon cannot be read
task_beyond_funded_horizon409The window could end after the funding does
task_exists409The stream already funds a task
task_delivery_invalid409The delivery claim is not usable
task_delivery_signature409The delivery is not signed by the task's payee
task_delivery_late409The delivery deadline has passed
task_already_delivered409The milestone already carries a delivery claim
task_not_submitted409The milestone carries no delivery claim
task_decision_invalid409The decision is not usable
task_decision_signature409The decision's signature does not verify
task_decision_stale409The decision is too far from engine time
task_not_evaluator409The signer may not make this decision
task_window_closed409The acceptance window has ended
task_stream_halted409The task's stream is halted
task_stream_bound409The stream funds a task
task_payment_pending409Accepted work is not yet paid
task_standard_unknown409The rejection names no declared standard
task_stream_exceeded409The streamed allowance is used up
task_closed409The task or milestone is already decided
ramps_off409Ramps are off on this deployment
ramp_budget_unfundable409The budget cannot take an on-ramp
ramp_quote_expired409The ramp quote expired
ramp_fee_not_accepted409The fee was not accepted
ramp_idempotency_conflict409The idempotency key or quote is already used
ramp_delivery_unverified409The chain does not show the ramp's stablecoin movement
ramp_tx_reused409The transaction already backs a ramp record
ramp_payout_exceeds_payin409The payout is larger than the payin
ramp_destination_missing409The payee has no verified wire destination
ramp_wrong_mode409The route does not apply in this ramp mode
ramp_unavailable409The ramp cannot run on this deployment
kya_off409KYA is off on this deployment
kya_unavailable409The verification provider is unavailable
kya_subject_unknown409The provider attests nothing for this agent
card_agent_token_unusable409The card agent token cannot fund this budget
card_agent_proof_invalid409The signed proof did not verify
card_agent_unavailable409The card agent program is unavailable
card_agent_merchant_not_allowed409The token does not allow this merchant
card_agent_cap_exceeds_token409The budget cap is above the token's limit
card_agent_controls_conflict409The token's controls and the mandate do not overlap
card_agent_idempotency_conflict409The idempotency key is already used
card_agent_card_number400A card number was sent
rate409The per-second allowance is used up
payer_concurrency409Too much concurrent unpaid work
cap409The spending cap is reached
mandate_category409The category is outside the mandate
mandate_depth409The delegation is too deep
mandate_widen409A child mandate may only narrow
amend_floor409The new cap is below committed work
amend_widen409An amendment may only narrow
amend_state409The stream cannot be amended now
not_found404Not found
state_conflict409The action does not fit the current state
invalid_request400The request failed validation
unauthorized401Missing or invalid owner token
scheduler_conflictnone (start-up refusal)Another scheduler holds this database; the deployment refuses to start
asset_currencynone (start-up refusal)The contract v2 asset is not listed as USD; the deployment refuses to start
chain_unreachable503The chain RPC is unreachable or refused the transport; the body never carries the RPC URL
revenue_channel_unknown404Unknown revenue channel
revenue_channel_locked409The revenue channel is locked
vault_paused409The stablecoin vault is paused
vault_owner_unqualified409The vault's owner is not a qualifying multisig
fee_collector_unqualified409The vault's fee collector is not a qualifying multisig
protocol_fee_mismatch409The vault's fee differs from the configured fee
internal500Internal error
payee_unverified409The payee is not verified on the credit card rail
payee_no_destination409The payee has no credit card payout destination
payee_credential401No valid payee credential
payee_consent400The payee consent was refused
destination_ownership422The proof is not signed by the destination address
card_rail_not_configured409This deployment has no credit card rail
wire_bank_unverified422The provider does not report this bank account as usable
wire_own_account409Own-account mode stores no wire destination
invalid_signature400The Connect webhook signature does not verify
event_id_missing400The Connect webhook event has no event id
invalid_json400The Connect webhook body is not JSON
parent_not_open409The parent stream cannot take a child
parent_headroom_exhausted402The parent has no room for this child
pay_signature_required409The payment needs the payer's and payee's own signatures
pay_wrong_signer409The hop is not signed by its delegator
pay_consent_session403Only a signed-in console click can consent
pay_consent_card_only409Consent pays from a credit card budget only
pay_intent_unavailable409The delegator has no mandate to sign against
pay_budget_inactive409The budget is closed
pay_frozen409The budget or the paying stream is frozen or stopped
pay_pending409The payment's stream opened this second
pay_unsigned503No signed voucher covers the payment yet
request_ref_conflict409The requestRef was used for a different payment, stream or payment authorization
csrf_invalid403The request did not come from this deployment's own page

Enterprise: policies

CodeHTTPMeaning
policy409A policy refuses the action
policy_invalid409The policy document is malformed
policy_version409The policy version is not the next one
policy_scope409The policy scope cannot take a policy
policy_not_found409The dry-run names a stream of another budget
policy_binding409The binding cannot change

Enterprise: recourse

CodeHTTPMeaning
recourse_claim_invalid409The case names no objective fact
recourse_exists409A case is already open on this fact
recourse_state409The case cannot do this now
recourse_pending409The facts are not settled yet
recourse_answer_invalid409The answer is malformed
recourse_answer_signature409The answer is not the payee's
recourse_unavailable409Terms cases are not available here

Enterprise: organisations and roles

CodeHTTPMeaning
role_forbidden403The member's roles do not allow this
org_forbidden403Self-grant or funder-grant refused (answered as role_forbidden)
org_exists409That id or member is taken
org_scope409Not in this organisation
org_assigned409The budget is already assigned
org_not_found404Declared, not sent: an unknown organisation answers not_found

Enterprise: single sign-on

CodeHTTPMeaning
sso_request400The callback is missing its parameters
sso_state403The OIDC login state is unknown, used or expired
sso_token403The identity provider's ID token is not usable
sso_not_member403This identity holds no role here
sso_session401No live member session
sso_csrf403The member session's CSRF token is missing or wrong