Every Nextbridge error returns the same JSON shape with a stable string code. Switch on the code, not the message — messages may be reworded; codes are part of the API contract.
Error shape
REST endpoints, MCP tool calls, and webhook deliveries all use the envelope below. Successful responses are { "data": ... }; failures are{ "error": { "code", "message", "details?" } }.
jsonHTTP 422
1{
2 "error": {
3 "code": "INSUFFICIENT_FUNDS",
4 "message": "Insufficient USDT balance (have 12.40, need 50.00)",
5 "details": null
6 }
7}
Error codes
Code
HTTP
When it fires
VALIDATION
422
Request body or query failed schema validation. Fix the input.
UNAUTHORIZED
401
No session cookie, or API key is missing/malformed in the Authorization header.
FORBIDDEN
403
Authenticated, but not allowed — e.g. USER key calling an ADMIN tool, or 2FA missing for a withdrawal.
NOT_FOUND
404
The referenced coin, order, alert, or address does not exist on this account.
CONFLICT
409
State conflict — duplicate alert, idempotency key reused with a different body, etc.
INSUFFICIENT_FUNDS
422
Trade or withdraw amount exceeds available balance (after holds).
RATE_LIMITED
429
Per-key bucket exhausted. See /developers/rate-limits.
UPSTREAM
503
A downstream price oracle or chain node is unavailable. Safe to retry after a few seconds.
Idempotent retries
Write endpoints accept an Idempotency-Key header. Replay the exact same request with the same key within 24 hours and you will get the cached response back withX-Idempotency-Replay: true — the underlying action does not execute twice. Use this for safe retries on network errors. 5xx responses are not cached, so a transient failure can be retried freely without a different key.