Errors
Every error is JSON with a stable machine code and a human message:
HTTP/1.1 409 Conflict
{ "error": "endorsement_required", "message": "Bridge has not approved this customer for EUR (the sepa endorsement). …" }Branch on error, never on message. A refused write changes nothing unless the answer says otherwise (POST /v1/payment_setups lists what it created before a later step was refused).
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 | The request is malformed or a field is invalid | Fix the field the code names |
| 401 | No key, an invalid or revoked key, or a key for the other environment | Check the key and the base URL |
| 403 | The key may not do this (scope, platform funds, paused product) | Do not retry; ask SET if you expect access |
| 404 | No such object for this key, or a sandbox route in production | Check the id; objects are scoped to the key's account and mode |
| 409 | The request conflicts with state: not yet verified, missing endorsement, already linked, not ready | Wait for the state to change, or fix the conflict |
| 422 | idempotency_key_reused: the same Idempotency-Key with a different body | Use a new key |
| 429 | Rate limited | Back off and retry |
| 500 | handler_error | Retry with the same Idempotency-Key; contact SET if it persists |
| 502 | The provider or a chain did not answer usably (rate_unavailable, chain_unavailable) | Retry shortly |
| 503 | The feature is not switched on for this deployment (api_disabled, webhooks_unconfigured, direct_deposit_disabled) | Ask SET |
Codes by area
| Area | Codes |
|---|---|
| Keys | api_key_required, api_key_invalid, api_key_wrong_mode, scope_missing, platform_api_paused, rate_limited |
| Customers | external_id_invalid, type_invalid, name_invalid, email_invalid, endorsements_invalid, endorsement_invalid, redirect_uri_invalid, customer_unknown, customer_type_conflict, email_already_onboarded, verification_incomplete, endorsement_required, merchant_single_customer, merchant_name_mismatch |
| Bank accounts | currency_invalid, account_type_invalid, bank_details_refused, bank_account_required, bank_account_unknown, bank_account_already_linked, bank_account_conflict, bank_currency_mismatch |
| Addresses and accounts | chain_invalid, rail_invalid, rail_currency_mismatch, stablecoin_invalid, reference_invalid, asset_invalid, address_invalid, route_not_supported, settle_route_not_supported, return_address_invalid, return_address_required, cash_out_address_invalid, cash_out_address_unknown, cash_out_address_conflict, virtual_account_invalid, virtual_account_unknown, account_conflict |
| Travel Rule | beneficiary_invalid, wallet_type_invalid, ownership_verified_at_invalid, sender_invalid, sender_type_invalid, deposit_not_ready, platform_details_incomplete, platform_funds_not_allowed |
| Payment setups | way_invalid, field_not_used |
| Events | after_invalid, webhook_url_missing, webhooks_unconfigured |
| Sandbox | nothing_to_simulate |
| Direct Deposit | partner_key_required, partner_key_invalid, direct_deposit_disabled, month_invalid, chain_invalid, address_invalid |
| Payable Email | payable_email_disabled, payable_email_off, payable_email_merchant, email_invalid, payee_invalid, payee_unknown, claim_needs_base, payee_cap_reached, tx_hash_invalid, payment_not_claimable, payment_mismatch, sender_unregistered, amount_out_of_range, tx_already_reported, privy_unavailable, chain_unavailable |
Compliance refusals
Some refusals come from the compliance programme rather than validation: a customer who is rejected, a movement without the Travel Rule data the provider requires (refused before it is sent), a beneficiary that is not allowed, or a key revoked after a sanctions or monitoring decision. SET does not explain a sanctions or suspicious-activity decision in an error message; see Monitoring and reporting.