Error reference

Every error you can hit while integrating with Noether, in one place: the HTTP errors the gateway returns, how failed on-chain transactions surface in API responses, and the complete contract error code tables for the market, Trader Vaults, and referral contracts. Bookmark this page and search by error name or code.

All examples below are against the live gateway at https://noetherapi-production.up.railway.app (Stellar testnet).

Gateway HTTP errors

The gateway returns JSON error bodies with a machine-readable error field (or a Fastify validation shape for schema failures). Summary first, exact bodies below.

400 — validation and preparation failures

Schema validation failures use Fastify’s built-in shape. Example (invalid candle interval):

{
  "statusCode": 400,
  "code": "FST_ERR_VALIDATION",
  "error": "Bad Request",
  "message": "querystring/interval must be equal to one of the allowed values"
}

POST /v1/orders/prepare adds two of its own:

{"error": "unsupported_asset", "asset": "XYZ"}

{"error": "simulation_failed", "message": "Simulation failed: ..."}

A simulation_failed at prepare time usually means the trade would revert on chain — insufficient collateral, a paused market, a contract error. Read the message: it often contains the underlying contract error. See how on-chain errors surface below.

401 — authentication failures

Authed endpoints expect Authorization: Bearer <keyId>:<secret> in a single header. See Authentication for the full scheme. The four failure bodies:

{"error": "missing_bearer"}

{"error": "malformed_bearer", "hint": "use Bearer <keyId>:<secret>"}

{"error": "stale_timestamp"}

{"error": "invalid_credentials"}

stale_timestamp only occurs if you send the optional X-Timestamp header (unix seconds) and it drifts more than 30 seconds from server time. Key issuance (POST /v1/keys) has its own 401:

{"error": "invalid_signature"}

Causes: the challenge expired (5-minute TTL), was already used, the signature does not verify against the claimed address, the transaction is a fee-bump, or the first operation is not the expected manageData op carrying the challenge bytes. Challenges are also held in gateway process memory, so a gateway restart voids outstanding challenges — request a fresh one and retry.

403 — closed beta

API key issuance is currently gated to early-access wallets. A non-allowlisted address gets:

{
  "error": "not_in_beta",
  "message": "API key issuance is currently restricted to early-access wallets. Contact the team to request access."
}

The gate applies at key issuance only. Public endpoints stay public, and a key you already hold keeps working. Check gating state without auth via GET /v1/keys/beta-status.

404 — not found

Unknown routes return Fastify’s default:

{"message": "Route GET:/v1/nope not found", "error": "Not Found", "statusCode": 404}

Resource-specific 404 bodies:

{"error": "Unknown asset", "asset": "FOO"}

{"error": "vault_not_found", "id": 999}

{"error": "unknown_code", "code": "NOSUCH"}

{"error": "no_code", "address": "GDA4..."}

{"error": "key_not_found"}

Note the asymmetry: GET /v1/markets/{asset} and GET /v1/markets/{asset}/price return 404 for unknown assets, but GET /v1/candles does not — it returns 200 with an empty candles array instead.

429 — rate limited

Limits are per fixed 60-second window aligned to the wall-clock minute: 60 requests/min unauthenticated (per IP), 600 requests/min with a standard API key (per key). Every rate-limited response carries X-RateLimit-Tier and X-RateLimit-Remaining headers; /v1/health and /docs are exempt. Sending a valid bearer key on any endpoint — even a public one — moves you to your key’s higher bucket.

On breach you get a Retry-After header (seconds until the window resets) and:

{"error": "rate_limited", "retry_after_sec": 37}

Back off until retry_after_sec elapses, then resume.

451 — region restricted

The trading endpoints (/v1/orders* and /v1/tx*) can be geo-restricted. When the restriction applies you get HTTP 451:

{
  "error": "region_restricted",
  "message": "Trading is not available in your jurisdiction. See the Terms of Service (restricted persons)."
}

This response is configuration-dependent — treat it as a possible response on the trading endpoints and handle it terminally (do not retry). Read-only endpoints, authentication, and /v1/health are outside the geo-guarded surface and are not geo-restricted.

5xx — upstream failures

{"error": "rpc_error", "message": "..."}

HTTP 502: the gateway could not reach Soroban RPC. Retry with backoff.

{
  "error": "try_again_later",
  "retryable": true,
  "hash": "...",
  "message": "RPC transaction queue is full — resubmit the same signed XDR shortly"
}

HTTP 503, with Retry-After: 2: the RPC transaction queue is full. Resubmit the same signed XDR after the delay — POST /v1/tx/submit is idempotent, so resubmitting is safe and returns the prior result if the transaction already landed.

How on-chain errors surface

Noether contracts fail with typed Soroban contract errors — on the wire they look like Error(Contract, #22). The gateway decodes these for you at two points in the trading flow:

At prepare time. POST /v1/orders/prepare simulates the transaction before returning the unsigned XDR. If the contract would revert, you get 400 simulation_failed and never need to sign anything.

At submit time. POST /v1/tx/submit decodes contract errors from the transaction’s diagnostic events into a structured contractError object:

{
  "hash": "85895449a4...",
  "status": "FAILED",
  "contractError": {"code": 22, "name": "InsufficientCollateral"},
  "resultXdr": "AAAA..."
}

A transaction rejected before inclusion returns 400 submission_rejected with the same optional contractError field. In both cases contractError is null when the failure is not a contract error (resource budget exhaustion, a Soroban auth failure, and so on) — inspect resultXdr for those.

Two things to know when decoding:

• The gateway’s decode map mirrors the shared NoetherError table below, with one gap: code 43 (DepositCapExceeded) is missing from the gateway’s map today. It — like any code the gateway does not recognize — decodes as "UnknownContractError" with the raw code preserved, so match on code, not name.
• Each contract has its own code space. NoetherError covers the market contract (and the shared vault, oracle shim, and router errors). Trader Vault (FactoryError) and referral (ReferralError) codes overlap numerically with the low NoetherError codes — disambiguate by which contract your transaction invoked.

Market and shared contract errors (NoetherError)

Shared by the market contract, the Liquidity Vault, the Noeracle shim, and the Noether Router. Codes are grouped in ranges by category.

General (1–19)

Position (20–29)

Oracle (30–39)

Vault (40–49)

Liquidation (50–54)

Funding (55–59)

Order (60–75)

Cross margin (76–82)

Trader Vault errors (FactoryError)

Raised by the Trader Vaults (vault factory) contract. These share numbers with low NoetherError codes — attribute by contract.

A note on #11: because the leader must always hold at least 5% of shares, an outside depositor cannot make the first deposit into an empty vault (the leader seeds it first), and total outside deposits are bounded relative to the leader’s stake. See Trader Vaults.

Referral errors (ReferralError)

Raised by the referral contract.

Next steps

• Trading endpoints — the prepare → sign → submit flow where contractError appears
• Authentication — bearer keys, the wallet challenge, and the 401 family
• Trading mechanics — the parameters behind the position and margin errors
• API explorer — try the endpoints live