Error Codes

Purpose

This page defines the public error taxonomy Norynta clients should use for retry behavior, alerting, and operator remediation.

The live taxonomy is also exposed through:

GET /api/bot/config -> execution.errorTaxonomy
POST /api/v1/developer/explain-error
GET /api/v1/status

Error Shape

Most API errors return a JSON object with at least an error string. Some routes also include a machine-readable code, requestId, or remediation metadata.

Representative shape:

{
  "error": "Rate limited",
  "code": "RATE_LIMITED",
  "requestId": "req_..."
}

When code is absent, clients should classify by HTTP status and exact endpoint context, then log the raw body for diagnostics.

Global Codes

Code	HTTP	Retryable	Meaning	Client behavior
`UNAUTHORIZED`	401	no	Missing or invalid credentials	Refresh or replace credentials
`FORBIDDEN`	403	no	Scope, policy, country, or compliance block	Stop writes and inspect access state
`NOT_FOUND`	404	no	Resource or endpoint not found	Check identifiers and API version
`RATE_LIMITED`	429	yes	Quota exceeded	Back off with jitter and preserve idempotency identity
`TRADING_PAUSED`	503	yes	Trading temporarily paused	Stop writes, continue read-only reconciliation
`LIVE_TRADING_DISABLED`	503	yes	Live trading disabled for environment or control state	Stop writes and monitor discovery metadata
`INTERNAL_ERROR`	500	yes	Unexpected server failure	Retry with capped backoff when safe

Validation And Payload

Code	HTTP	Retryable	Meaning
`INVALID_JSON`	400	no	Request body is not valid JSON
`INVALID_PAYLOAD`	400	no	Required fields are missing or malformed
`MISSING_IDEMPOTENCY_KEY`	400	no	Mutating v1 request did not include `Idempotency-Key`
`IDEMPOTENT_REPLAY`	200/409	no	Same logical write was replayed
`ACCEPTED_UNKNOWN_CONFIRMATION`	202/504	conditional	Write may have been accepted but confirmation is unknown

For IDEMPOTENT_REPLAY, treat exact replay as recovery and reconcile by clientOrderId. Do not create a new logical order after an uncertain write.

Trading And CLOB

Code	HTTP	Retryable	Meaning	Client behavior
`CLOB_INVALID_ORDER`	400	no	Order payload fails CLOB validation	Fix payload before retry
`CLOB_INVALID_SIGNATURE`	400/401	no	Wallet signature does not match payload	Rebuild and re-sign
`CLOB_MISSING_SIGNATURE`	400/401	no	Signed write is missing wallet authorization	Add wallet signature headers/body
`CLOB_EXPIRED`	400	no	Signature or order freshness window expired	Request a fresh signature
`INSUFFICIENT_BALANCE`	400/402	no	Not enough collateral for intended order	Reduce size or add funds
`STALE_ORDERBOOK`	409	yes	Preflight data is stale	Refresh snapshot/orderbook and rerun checks
`MARKET_CLOSED`	409	no	Market is closed or resolved	Stop writes for that market
`MARKET_PAUSED`	409/503	yes	Market writes are paused	Stop writes and monitor market state
`SIMULATION_DISABLED`	410	no	Legacy simulation endpoint is disabled	Use `/api/v1/orders/validate` or `/api/v1/orders/estimate-impact`

Country And Access Controls

Code	HTTP	Retryable	Meaning
`GEO_BLOCKED`	403	no	Jurisdiction is blocked
`GEO_UNKNOWN`	403	no	Country could not be determined for real-money behavior
`REAL_MONEY_COUNTRY_NOT_ALLOWED`	403	no	Country is not allowed for real-money writes
`REAL_MONEY_COUNTRY_NOT_APPROVED`	403	no	Country requires additional approval

Read-only discovery may remain available when real-money writes are blocked. Do not retry with proxy or VPN country spoofing.

Streaming

Condition	Retryable	Client behavior
Stream disconnect	yes	Reconnect and fetch a fresh snapshot before trusting new deltas
Heartbeat timeout	yes	Treat as disconnect and reseed
Sequence gap	yes	Pause strategy writes, request replay, then refresh snapshot if replay is unavailable
Duplicate sequence	no	Ignore duplicate for the same channel key

The stream contract is available at GET /api/v1/streams/manifest.

Explain An Error

curl -sS -X POST "$NORYNTA_BASE_URL/api/v1/developer/explain-error" \
  -H 'content-type: application/json' \
  -d '{"code":"RATE_LIMITED","requestId":"req_example"}' | jq

The response maps the code to retryability and remediation guidance.

Client Policy

Retry 429, network timeouts, and selected 5xx with capped exponential backoff and full jitter.
Reuse the same clientOrderId and Idempotency-Key across write retries.
Do not retry validation, payload, signature, country, or compliance failures unchanged.
Reconcile before replacing an order after an unknown write outcome.
Log request IDs, idempotency key hashes, and stable order IDs.

Related Docs

docs/public/AUTH_AND_RATE_LIMITS.md
docs/public/TRADING_INTEGRATION_WORKFLOW.md
docs/public/STREAMING_AND_RECONCILIATION.md
docs/public/API_REFERENCE.md