Errors¶

The envelope¶

Every failure the API raises comes back in the same three-key shape:

{
  "statusCode": 422,
  "message": "INVALID_INVOICE_AMOUNT",
  "timestamp": "2026-01-14T09:00:00.000Z"
}

message is an error code — an upper-case identifier such as INVALID_INVOICE_AMOUNT, never a sentence. It is stable, machine-readable, and what you should branch on. There is no separate code field and no field-level breakdown of what was wrong with your body — a 400 INVALID_REQUEST_BODY tells you the body was rejected but not which field did it.

Two errors carry a fourth key, details. 422 NOTHING_TO_SWEEP adds the amount left on the address and the network fee that moving it would cost; see sweeping a deposit address. 422 DESTINATION_NOT_ACTIVATED adds minAmount, the smallest payout that creates the recipient's account; see withdrawing to RIPPLE. No other error has details.

statusCode duplicates the HTTP status. timestamp is when the error was produced, in UTC.

Generic codes¶

A failure with no more specific code answers with the generic code for its status — a route that does not exist, for instance, is 404 NOT_FOUND.

Treat a code you do not recognise by its status, using the table in retrying.

By status¶

400 — the request was malformed¶

Never retry a 400. The request will be rejected identically every time.

401 — you were not identified¶

The four causes are deliberately indistinguishable, so there is nothing to be learned from the response about which one applies.

403 — identified, but not allowed¶

Note the difference between PERMISSION_DENIED and 404: an id that exists but is not yours is a 403; an id that exists nowhere is a 404. So a 403 on a GET confirms the resource exists.

404 — nothing there¶

The two bolded rows are mismatch errors reported as lookups: a real paymentId under the wrong invoiceId reports the payment missing, and a real tokenId paired with the wrong chainId reports the token missing. Check the pairing before you conclude the id is bad.

WALLET_NOT_FOUND is the one exception to the 403-for-someone-else's rule above: sweeping an address of another merchant answers 404, so the answer does not confirm the id exists.

409 — it already exists¶

GET /api/v1/invoices?externalId=order-1043&limit=1

422 — well-formed, but not permitted¶

The largest family. The request parsed and the resources exist; the state does not allow the operation.

A 422 is never worth retrying unmodified. Either the state has to change or your request does.

5xx — the request failed on our side¶

Every 5xx answers INTERNAL_ERROR. The code does not say what failed; the status says roughly where.

Retrying¶

Use exponential backoff with jitter, and cap the attempts. Retrying a 502 without a limit during an upstream outage only adds load to it.

A worked handler¶

resp = requests.post(url, headers=headers, json=body, timeout=30)

if resp.ok:
    return resp.json()

err = resp.json()
message = err.get("message")

if message == "INVOICE_EXTERNAL_ID_ALREADY_EXISTS":
    return fetch_invoice_by_external_id(body["externalId"])   # not an error for you
if message == "MERCHANT_BLOCKED":
    raise AccountBlocked()                                     # page someone
if resp.status_code >= 500:
    raise Retryable(message)                                   # backoff and try again
raise Permanent(f"{resp.status_code} {message}")               # log the full envelope

Log the whole envelope, timestamp included, on every branch. It is what support needs to locate a single request.