Errors

Every error from every route is one JSON body:

{
  "statusCode": 422,
  "message": "Insufficient available balance",
  "error": "InsufficientAvailableBalance"
}

• Switch on error — it is a stable code. message is text for people, not for parsing. It is an array only for body validation failures, one entry per rejected field.
• Ignore codes you do not know. New ones can be added under v1.

By status

Status	Meaning	What to do
400	Malformed request, a required header missing, or an amount with more than two decimal places (AmountPrecisionExceeded)	Fix the request. Do not retry as-is. See Amounts.
401	Authentication failed	Check clock, signed path, signed bytes, key id.
403	A scope is missing	Ask Neo Wallet support to grant it.
404	Not yours, or does not exist	—
409	Same idempotency key still in flight; duplicate; state conflict	Wait and retry the same key.
422	A business rule refused it	Read error (below). Retrying unchanged will fail again.
429	Rate limit	Back off, retry.
500	Fault on our side	Retry with the same key; if it persists, send us X-Request-Id.
503	Temporarily unable to process the request	Retry with the same Idempotency-Key.

422 codes you can act on

error	Fix
InsufficientAvailableBalance	The wallet cannot cover amount + fee + tax. Quote first.
CurrencyMismatch	currency must equal the wallet's currency.
AuthorizationInsufficient	The assertion expired, or a second factor is required.
AssertionNotBoundToTransaction	Rebuild the transaction binding from the request you are sending.
FundingAccountNotConfigured	Your prefunded balance is not set up yet — contact support.
FundingNotPositioned	Your prefunded balance does not cover the credit — top it up.
MandateNotActive	The mandate is pending, suspended, revoked or expired.
MandateAmountExceeded	The debit is above the mandate's amount rule.
MandateFrequencyExceeded	The mandate was already debited this period.
RailUnavailable	The payment provider (railCode) is unavailable for this operation. Try later or another one.
RequiredAgreementsMissing	POST /customers needs an accepted wallet_opening, privacy and fee_schedule agreement. Resend with all three.
UnprocessableEntity	A limit, account-status or compliance refusal, or an idempotency key reused with a different body. No further detail is given.

Each route's page in the API reference lists the statuses it answers with.