Errors

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:

# 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... }'

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.

Signed requests

akid_* credentials authenticate by signature, not by presenting a bearer
secret. The complete key id identifies you; the signature proves you hold
the private half, which we never had and cannot leak.

There are two ways to do it, and the first needs no library and no
canonicalisation.

Ask us what to sign. Send the request with no signature. You get 202
with payloadToSign and requestId, and nothing has happened yet. Sign
payloadToSign with your private key — ECDSA P-256 over SHA-256 — and send the
same request again with X-Anzo-Signature and X-Anzo-Request-Id. That is the
whole integration. The challenge is single-use and bound to that exact request,
including its Idempotency-Key, so it cannot be spent on another one.

Or sign the request yourself with X-Anzo-Signature, X-Anzo-Timestamp and
X-Anzo-Nonce, which saves a round trip and is worth it for a payroll run of
thousands. @avvio/payments does this for you.

SIGNATURE_INVALID is deliberately one answer for several causes — a wrong
key, an unreadable key, a tampered request. Telling them apart only helps
somebody guessing. In practice it is almost always one of two things: the body
was re-serialized after signing (sign the exact bytes you send), or a proxy
rewrote the path, which is part of what you signed.

SIGNATURE_TIMESTAMP_SKEW names the clock because that is what it nearly
always is. Check NTP on the sending machine before suspecting the key.

SIGNATURE_REPLAYED means the nonce has been used. Every request needs its own
— a UUID per call is fine. This is the guard Idempotency-Key cannot provide,
because you choose that value and so could anyone who captured your request.

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.