Errors, limits and versioning

Error format#

Every error from /api/dex/v1 has the same JSON shape and an HTTP status that matches it:

{
  "success": false,
  "error": {
    "schema_version": "botradix-dex-error-v1",
    "code": "SCOPE_NOT_ALLOWED",
    "message": "…",
    "retryable": false,
    "details": {},
    "request_id": "dxr_…"
  },
  "request_id": "dxr_…",
  "api_version": "v1",
  "api_schema_revision": "botradix-dex-api-v1.1"
}

Use error.code in your logic (messages can change) and keep request_id when you contact support. retryable: true means the same request may succeed later.

Common errors#

Version 2.2 codes#

When inverting next to an opposite-side net position with the same key, the response may return that net position's id: there is no DexPositionOpened, but a DexPositionChanged of the net position.

Why a prepared action is not executable#

When prepare succeeds but execution.ready is false, execution.reason explains it:

Rate limits#

Each API key has its own limits, counted in 60-second windows:

Per-key quotas can be set when a key is created or rotated, up to these caps: requests 30,000, orders 12,000, burst 1,000, account reads 20,000 and historical reads 12,000 per minute.

On top of the per-key limits, the network edge allows up to 100 requests per second per IP address (bursts of 200) and 60 per second per API key (bursts of 120). Edge rejections are plain 429 responses without the JSON body.

Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds when the window resets) for the general per-key bucket. 429 responses carry no Retry-After: back off exponentially with jitter (for example 1, 2, 4, 8 seconds).

Retries#

• Retry on 429, on 5xx and when error.retryable is true, with exponential backoff.
• Reuse the same idempotency key, with the same body, when you retry a prepare or an execute, so a lost response does not create a second preparation or a second order.
• Never blindly retry a broadcast transaction: check /transactions or /native/executions/{tx_hash} first.

Response headers#

Versioning policy#

• /api/dex/v1 is the stable integration contract. New fields and endpoints can be added to v1 without notice; your client should ignore fields it does not know.
• Changes that would break existing integrations are published under a new version.
• GET /meta returns the current schema revision and capabilities.
• Unversioned endpoints used by the web terminal (/api/dex/… without v1) can change at any time.