Errors

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 error code tables for the market, Trader Vault and referral contracts as deployed on testnet. Search this page by error name or code.

All examples are against the live gateway at https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io.

Gateway HTTP errors

The gateway returns JSON error bodies with a machine-readable error field. Summary first, exact bodies below.

400: validation and preparation failures

Schema validation failures carry the Fastify validation code in error, a human-readable message, and a validation array with the failing schema paths. Example (invalid candle interval):

{
  "error": "FST_ERR_VALIDATION",
  "message": "querystring/interval must be equal to one of the allowed values",
  "validation": [
    {
      "instancePath": "/interval",
      "schemaPath": "#/properties/interval/enum",
      "keyword": "enum",
      "params": { "allowedValues": ["1m", "5m", "15m", "1h", "4h", "1d", "1w"] },
      "message": "must be equal to one of the allowed values"
    }
  ]
}

Body validation runs before authentication, so a malformed POST /v1/orders/prepare body gets this 400 even without a key. POST /v1/orders/prepare adds two errors of its own:

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

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

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

401: authentication failures

Authenticated endpoints expect Authorization: Bearer <keyId>:<secret> and X-Timestamp (unix seconds) in every request. See Authentication for the full scheme. The failure bodies, in the order the gateway checks them:

{"error": "missing_bearer"}

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

{"error": "missing_timestamp"}

{"error": "stale_timestamp"}

{"error": "invalid_credentials"}

stale_timestamp means the X-Timestamp value drifted more than 30 seconds from server time. Key issuance (POST /v1/keys) has its own 401:

{"error": "invalid_signature"}

Causes: the challenge expired (five-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 a manageData op carrying the challenge bytes. Challenges are 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 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. Join the waitlist at noether.exchange to request access."
}

The gate applies at key issuance only. Public endpoints stay public, and a key you already hold keeps working. Check the 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": "NOSUCHCODE"}

{"error": "no_code", "address": "GCHAX2N74WJVZLATV7WETVWZRHM5RSOINGELOHP2BRXTEC7AHUXUHHIT"}

{"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 and source: "binance" instead.

409: key limit reached

POST /v1/keys refuses to mint another key when the wallet already holds the maximum number of active keys. The message states the count and the limit; revoke an unused key and retry.

{"error": "key_limit_reached", "message": "This wallet already has N active API keys (limit N). Revoke an unused key before issuing another."}

429: rate limited

Limits are per fixed 60-second window aligned to the wall-clock minute: 60 requests per minute unauthenticated (per IP), 600 requests per minute with a standard API key (per owning wallet). Every rate-limited response carries X-RateLimit-Tier and X-RateLimit-Remaining headers; /v1/health and /docs are exempt. Sending a valid key and X-Timestamp on any endpoint, even a public one, moves you to your wallet'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.

5xx: upstream failures

{"error": "rpc_error", "message": "Upstream RPC request failed."}

HTTP 502: the gateway could not complete its Soroban RPC call. The body is deliberately opaque; the full error is in the gateway's logs under the x-request-id of your response. Retry with backoff. On POST /v1/tx/submit the body also carries "retryable": true.

{
  "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 the transaction's diagnostic events into a structured contractError object, and a hostError object when the Soroban host aborted outside contract code:

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

A transaction rejected before inclusion returns 400 submission_rejected with the same contractError, hostError and txResultCode fields. contractError is null when the failure is not a contract error; in that case look at hostError (for example {"type": "budget", "code": "exceeded_limit"} for a resource overrun, or a storage trap when the ledger state moved between simulation and apply, which a fresh prepare fixes) and txResultCode.

Two things to know when decoding:

• The gateway maps the code number to a name from its own copy of the NoetherError table below. A code it does not recognize decodes as "UnknownContractError" with the raw number 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. This is the enum in the deployed market contract's interface; the numbers 51, 63 and 68 are intentionally unused and never reassigned.

General (1 to 19)

Position (20 to 29)

Oracle (30 to 39)

Vault (40 to 49)

Liquidation and funding (50 to 59)

Order (60 to 75)

A slippage breach on execution does not raise an error: the order is cancelled with status CancelledSlippage and the collateral refunded.

Cross margin and risk controls (76 to 93)

Trader Vault errors (FactoryError)

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

See Trader Vaults for the leader minimum-holding rule and how it bounds outside deposits.

Referral errors (ReferralError)

Raised by the referral contract as deployed.

Next steps

• Orders and transactions: 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
• Generated reference: try the endpoints live