# State / Error / Recovery Matrix

**Author synthesis — proposed reviewer template. Not a provider state machine, industry standard, certification or Treasury Desk product feature.**

Provider-native states/codes remain separate from the author-normalized `certainty` and `condition` columns.

| condition | transport/tool result | payment state | certainty | side effects known/unknown | lookup evidence | documented recovery preconditions | disallowed inference/action | owner/escalation | closure evidence | source |
|---|---|---|---|---|---|---|---|---|---|---|
| Input rejected before execution | HTTP/provider validation failure | not established | KNOWN only if docs say endpoint not executed | usually no business side effect only when documented | error object | correct invalid input; use new request identity when provider requires | do not retry unchanged invalid payload | integration owner | corrected/new request outcome, if attempted | provider contract |
| Auth/policy denial | 401/403/native denial | not established or denied | KNOWN within source scope | economic side effect not inferred | auth/policy record | restore authority only through authorized process | do not change payee/amount/scope to bypass denial | authority owner | explicit new authorized decision | provider/policy |
| Business decline | request processed; decline code | provider-native declined state | KNOWN within provider scope | payment not successful in provider state; other side effects source-specific | payment object | provider-specific retry/new-intent rules | 4xx ≠ universal retry signal | payment ops | terminal provider evidence + finance handling as needed | provider |
| Rate limit | HTTP/native rate-limit result | unknown/not started depending contract | UNKNOWN unless execution boundary documented | unknown unless provider specifies pre-idempotency handling | error + request logs | wait/retry only per provider/client policy | do not infer safe replay solely from 429 | integration owner | later definitive response/state | provider |
| Concurrency conflict | conflict / in-progress | provider-specific | UNKNOWN/PARTIAL | duplicate risk depends on contract | object/idempotency lookup | wait/lookup or provider-specific handling | do not fan out retries | payment ops | resolved authoritative state | provider |
| Timeout after send | no definitive response | may be processed | UNKNOWN | side effects unknown | status/object/event/ledger lookup | gather evidence before new economic attempt | timeout ≠ failure; no new payment by default | payment ops + authority owner | definitive provider/settlement evidence or explicit unresolved disposition | HTTP + provider |
| Downstream communication error | upstream/provider adapter error | provider-specific | UNKNOWN/PARTIAL | depends on downstream execution | adapter code + native lookup | provider-specific evidence path | adapter message ≠ business truth | integration/payment ops | source-native state + reconciliation | provider |
| HTTP 202 | accepted, not completed | pending/unknown | UNKNOWN/PARTIAL | processing may still occur | status URI/object/event if documented | wait/lookup according to domain contract | 202 ≠ settled | payment ops | terminal provider + reconciliation evidence as required | RFC 9110 + provider |
| Callback received and ACKed | callback transport 2xx/ACK | payload contains provider state observation | PARTIAL | receipt known; business completion depends on payload/source | authenticated callback + object lookup | verify authenticity, dedupe, process | ACK ≠ business completion | event handler/payment ops | correlated provider + reconciliation evidence | provider |
| Duplicate callback | repeated event | same logical business event possible | KNOWN duplicate only with stable identity | no new logical payment inferred | event ID/object ID | dedupe per documented identity | do not count duplicate delivery as duplicate payment | event owner | one preserved event history | provider |
| Out-of-order callback | late event | potentially older or conflicting state | CONFLICTING/PARTIAL | arrival order not business order | event/source times + object retrieval | preserve history, resolve with authoritative source | latest arrival ≠ truth | payment ops | resolved state with provenance | provider |
| Idempotent retry within documented scope | repeated request | provider-specific same-effect semantics | PARTIAL/KNOWN per docs | depends on key scope/lifetime/equivalence | idempotency record + object | same provider/scope/equivalent payload and unexpired semantics | idempotency ≠ exactly-once end-to-end | integration owner | authoritative provider result | provider |
| Same key, changed parameters | provider error or undefined/blocked depending contract | unknown/unchanged | KNOWN conflict when contract rejects mismatch | side effects from original remain possible | idempotency/object evidence | treat as changed intent/new review | do not assume key “updates” original intent | authority owner | new approved intent + separate attempt | provider |
| Failover while first outcome unknown | second provider candidate | two economic attempts possible | CONFLICTING/UNKNOWN | duplicate economic side effect possible | provider A + B evidence | resolve first or human-authorized exception | do not assume key/guarantee transfers | human disposition owner | both providers reconciled | author method |
| Cancellation requested | API/tool accepts request | original may still be pending/processed | PARTIAL | rollback not established | cancel operation ID/status | provider-specific cancellable state + authority | cancel request ≠ confirmed cancellation | payment ops | confirmed cancellation + downstream reconciliation | provider |
| Refund requested | recovery child accepted/pending | original payment remains historical fact | PARTIAL | economic recovery not final | refund child record | captured/settled state and refund authority | refund ≠ atomic rollback | payment ops | refund terminal state + reconciliation | provider |
| Reversal/void | provider-specific recovery | source-specific | PARTIAL | terminology/state provider-specific | child operation | documented preconditions | do not map universally | payment ops | provider final state + reconciliation | provider |
| Reconciliation matched | transport irrelevant | finance record matched to expected obligation | KNOWN for selected criterion | downstream closure evidence known | ledger/report/workpaper | selected case-closure policy | reconciled ≠ legal finality in every domain | finance reviewer | explicit closure record | finance/source |