Errors

The error shape

An error is not wrapped in the success envelope. It has its own shape:

{
  "statusCode": 400,
  "timestamp": "2026-09-02T10:17:34.221Z",
  "path": "/api/partner/v1/deposits",
  "method": "POST",
  "message": "amount carries more fractional digits than USD settles at",
  "code": "AMOUNT_PRECISION_EXCEEDED",
  "allowedDecimals": 2,
  "details": { "allowedDecimals": 2 }
}

An unexpected server fault has no code and reads "message": "An unexpected error occurred". Treat it as a network error. See Handling 5xx.

HTTP statuses

The code catalogue

Read the Retry column first.

• Same key — safe to resend the identical request with the same Idempotency-Key.
• New key — nothing moved; a fresh request under a fresh key is safe.
• Poll — money may have moved or already completed. Re-read the intent under the original key. Never resubmit.
• Fix first — a retry cannot succeed until you change something.

Handling 5xx and network errors

A timeout, a dropped connection or a 500 on a money route tells you the request may have been carried out. It never tells you it was not.

Resend the identical request with the same Idempotency-Key. The mechanics are in Conventions. One of four things comes back.

Practical advice:

• Retry only idempotent-safe conditions: 429, 503, connection errors, and timeouts. Exponential backoff, with a ceiling.
• Never generate a new idempotency key on a retry path. Mint the key when you first decide to move money, persist it beside your own record, and reuse it for every attempt at that movement.
• Log the code, the message and your idempotency key together. Those three resolve almost every support request.

Pilot disclosure