Errors

Three questions sit behind every failure on this page: did the request execute, is retrying safe, and what do I do now. The first two are marked on every row below, because at 3am they are the only ones that matter and prose is the wrong medium for them.

No error type on this page means "the payout was sent and then failed". That is not an error response at all — it is a payout whose status is failed, carrying a failureCode. Those are further down.

Every failure has the same shape. Branch on type — it is stable across versions, where the HTTP status and the prose are not.

{
  "type": "RATE_DRIFT_EXCEEDED",
  "status": 400,
  "detail": "Refusing to send: quoted 3384.65 but you expected ~9999 (6615 bps of drift, limit 200). Nothing was sent.",
  "resolution": "Nothing was sent. Re-quote, show the payer the new amount, and send again.",
  "requestId": "req-1c"
}

resolution says what to do, when there is a specific answer. It is not on every error — treat it as optional and fall back to detail, which is always present. (An earlier version of this page listed exactly which types omit it; the list was incomplete, and an incomplete enumeration is worse than saying "optional".)

requestId is in the body of every error, and on a SUCCESSFUL response it is the x-request-id header rather than a body field. Log the header and you have it for every request either way. (This previously claimed the body carried it on success; it does not.)

Validation failures add errors, a list of the fields that failed. detail stays a string in every case, so detail.toLowerCase() is always safe.

Request errors#

BAD_REQUEST is the catch-all for a 400 that is not a field-validation failure. Because it covers several conditions, it is the one type where you should read detail — it names the specific condition. None of them is retryable unchanged.

There is no retryable field on the wire. An earlier version of this page told you to branch on one; the Node client derives it for you, but over raw HTTP the type is what you branch on.

Idempotency#

A 4xx releases the key — a request that failed validation committed nothing, so you may correct the body and reuse it.

DUPLICATE_REQUEST_DETECTED#

The key protects you only if your retry sends the *same* key. Some HTTP clients generate one per attempt, which defeats it silently: every retry looks like a new request, and every retry pays. So we watch a second signal — same body, different key, within 15 minutes — and refuse.

{
  "type": "DUPLICATE_REQUEST_DETECTED",
  "originalIdempotencyKey": "zz_advance_88213",
  "originalPayoutId": "pay_01J…",
  "detail": "An identical request was received in the last 15 minutes under a different Idempotency-Key…"
}

This is not "already paid". Nothing was executed. Reading it as a success and marking the wage settled is the one wrong move, and it leaves a worker unpaid with your ledger saying otherwise.

Two ways forward, and you have to pick one — we will not guess:

• It was a retry. Send it again with the value of originalIdempotencyKey as your Idempotency-Key header. That is the key the first attempt used, so this replays it: you get the original payout back and nothing is sent twice.

  copy

  # the 409 gave you: "originalIdempotencyKey": "zz_advance_88213"
  curl -s -X POST ".../payouts" \
    -H "idempotency-key: zz_advance_88213" \   # <- that value, as the header
    -H "content-type: application/json" \
    -d '{ ...the same body... }'

  originalIdempotencyKey is a field we send to you, not one you send back. Putting it in the request body is rejected — request bodies reject unknown properties.

• You meant two payments. Add X-Allow-Duplicate: true and send again. This sends a second real payment. Only take this branch if you are certain the first one was intended too.

The window is 15 minutes, and that is a real boundary. It covers a crashed job that requeues on a backoff — the realistic incident. It is deliberately not the full 7-day retention: content matching cannot tell a retry from a genuine repeat, and two advances of the same amount to the same worker in one week are ordinary payroll. At 7 days every routine repeat would be refused and you would end up sending X-Allow-Duplicate unconditionally, which removes the protection while appearing to strengthen it.

Send a unique reference per logical payment and this can never false-positive at any window length — a different reference is a different body. That, plus persisting your own idempotency key, is the durable protection. This guard is a net for the accidental case, not a substitute for either.

We refuse rather than silently returning the first payout, because *both* readings are common. Two advances of the same amount to the same worker in one week is ordinary payroll; replaying there would mean the second one never goes out while your ledger records that it did. A 409 you have to answer is recoverable. A payment that quietly evaporates is not.

How long a key is remembered#

Seven days, and the window is about storage, not correctness. There is no "the key expired, so we ran it again" path: while we hold the record it is authoritative, and an old key retried against it replays rather than re-executes. A TTL that quietly re-arms a key is a double payment on a timer.

Past seven days the record is deleted and the key is genuinely unknown to us — so treat seven days as the outer bound on retrying, not on caring. If you are reconciling something older, read the payout by id.

Sending#

DESTINATION_ACCOUNT_NOT_FOUND is the guard against paying an id you did not get from us. A stale, typo'd, or copied-from-elsewhere account id is refused before anything is priced — rather than being sent, settling, and reporting completed to a payroll run where nobody received the money.

INDICATIVE_PRICING_UNAVAILABLE#

GET /rates shows a price before a beneficiary exists — "you send $200, they get 3,410 MXN" while your user is still typing. Not every routing publishes one.

This is a permanent property of how your organization is routed, not an outage, so retrying will never succeed. Read capabilities.indicativePricing on the corridors call and, when it is false, skip straight to creating the beneficiary and pricing against it.

It used to surface as a 501 typed INTERNAL advising "retry with the same Idempotency-Key" — retry advice for a GET, on a condition that never changes.

Payout links#

A link that was already spent successfully is not an error: a repeat submit returns the original payout with status: "already_submitted", so a recipient who double-taps gets what they already have.

A 404 on a link route covers expired, spent, forged and never-existed alike — a stranger probing links learns nothing from the difference.

When a payout fails#

A payout that was accepted and later failed is not an error response — it is a payout whose status is failed, carrying a failureCode.

Read fundsReturned, not the code. It is the only field that answers "is the money back in my balance?", and it is absent when we do not yet know — which is deliberately not the same as false. Do not re-credit a user on a code alone.

The one case where it stays absent: compliance_rejected. Those funds are held pending a human review, so there is no automatic answer to give and we will not invent one. Absent here means "ask us", not "not yet" — contact us with the payoutId. Your ledger can still settle the question without waiting: the balance history shows the debit with no matching reversal entry, which is the positive statement that the money did not come back.

New failure codes are added without a major version. Treat an unrecognised one as execution_failed.

What the sandbox can and cannot produce#

Only three failure codes are reachable in sandbox — account_invalid (0001), compliance_rejected (0004) and returned_by_bank (0003). The rest (limit_exceeded, account_cannot_receive, authorization_not_completed, execution_failed, quote_expired, unknown) come from live rails only.

stage is likewise live-only and never appears on a sandbox payout.

So do not treat a sandbox run as proof your failure handling is complete. Write the switch for every code in the table, and make the default branch behave like execution_failed — you cannot test the others before go-live.

The one that surprises people#

completed → failed with returned_by_bank happens after you were told the payout succeeded, sometimes days later.

Keep processing webhooks for a payout after it completes, and do not write a ledger that treats completed as immutable. Trigger it on demand in sandbox with an account number ending 0003.