Errors¶

The envelope¶

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

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

message is the name of the error class, not a sentence. It is stable, machine-readable, and what you should branch on. There is no code field, no details, and no field-level breakdown of what was wrong with your body — a 400 InvalidRequestBodyError tells you the body was rejected but not which field did it.

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

Two exceptions¶

The envelope holds everywhere except in two places.

A rate that does not exist answers a different shape, because the gateway raises it directly:

{ "statusCode": 404, "message": "Rate not found", "error": "Not Found" }

Prose message, an extra error key, no timestamp. Only GET /api/v1/tokens/rate does this.

An unreachable upstream produces a bare:

{ "statusCode": 500, "message": "Internal server error" }

which means the request never got far enough to be classified. Treat it as retryable.

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¶

PermissionDeniedError versus 404 is worth internalising: 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 catch people out. Both are mismatch errors dressed 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.

MerchantWalletForChainTypeNotFoundError is a configuration problem, not a request problem — it means nobody has set up a payout wallet for that family in the cabinet. Retrying will not fix it.

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.

502 — an upstream failed¶

Retrying¶

Use exponential backoff with jitter, and cap the attempts. A client that retries a 502 forever during an upstream outage becomes part of the outage.

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 == "InvoiceWithExternalIdAlreadyExistsError":
    return fetch_invoice_by_external_id(body["externalId"])   # not an error for you
if message == "MerchantIsBlockedError":
    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. Quoting it makes a support conversation about a single request short instead of long.