Payments
Failure reasons
The complete taxonomy of declines, holds, and returns — and how to handle each.
Every non-success outcome carries a documented reason code. There are no opaque failures.
Screening outcomes
| Code | Meaning | Recommended handling |
|---|---|---|
sanctions_match |
Counterparty matched a sanctions list | Do not retry. Review the counterparty relationship. |
pep_review |
Politically exposed person — held for enhanced review | Wait for the review decision (webhook payment.cleared or payment.declined). Typical review: hours, not days. |
risk_threshold |
Transaction risk score exceeded corridor threshold | Held for review. Provide additional remittance context if requested. |
data_incomplete |
Counterparty or remittance data insufficient to screen | Fix the payload and resubmit with a new idempotency key. |
Validation and limits
| Code | Meaning | Recommended handling |
|---|---|---|
corridor_inactive |
Corridor not enabled for your account | Check /v1/capabilities; contact us to activate. |
quote_expired |
Persisted quote validity window elapsed | Request a fresh quote and resubmit. |
limit_exceeded |
Corridor or account limit reached | Retry after limit reset, or request a limit review. |
Post-settlement
| Code | Meaning | Recommended handling |
|---|---|---|
returned_by_beneficiary_bank |
Receiving institution returned the funds | Reconcile via the Return object; verify counterparty account data before retrying. See Returns. |
Displaying reason-appropriate messages to your users — instead of a generic failure — measurably reduces support contacts. Copy suggestions per state are provided in [Held for review](/sirius-core/held-for-review).