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 static text for humans and never quotes your input. 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, or a required header missing	Fix the request. Do not retry as-is.
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	Dependency down, or a concurrency race	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.
UnprocessableEntity	A limit, account-status or compliance refusal, or an idempotency key reused with a different body. Deliberately unspecific.

The authoritative list is the ApiError.error enum in openapi.json.