Errors and recovery

The catalogue and trading APIs use one failure contract. Handle failures by code; use the HTTP status only as a broad category. Never branch on title, detail, or a validation message because those strings are written for people and can change without changing the condition.

HTTP Problem Details

An error returned by the API origin uses application/problem+json:

HTTP/2 422 Unprocessable Entity
Content-Type: application/problem+json
X-Request-ID: 8051f907-4eeb-4ca9-bd84-b447ea65a68c

{
  "type": "urn:agara:problem:insufficient-balance",
  "title": "Insufficient balance",
  "status": 422,
  "code": "insufficient_balance",
  "detail": "Available balance is lower than the order value.",
  "request_id": "8051f907-4eeb-4ca9-bd84-b447ea65a68c",
  "recovery": {
    "strategy": "none"
  }
}

Clients should accept field_errors when present, but an endpoint is not required to provide it for every validation failure.

The response body and X-Request-ID header carry the same server-generated UUID. A request ID supplied by a client is not echoed back as the server ID.

Fix invalid requests

Invalid input is split into distinct conditions:

An order that is well formed but outside a published bound is a separate case, and each bound answers with its own code rather than validation_failed. See order size limits for the values.

A withdrawal to a wallet that cannot receive the destination token yet also has its own code. Nothing moves; change the recipient or prepare the wallet, then request a new quote.

A validation response can identify safe fields without repeating submitted values:

{
  "type": "urn:agara:problem:validation-failed",
  "title": "Request validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "One or more fields are invalid.",
  "request_id": "8051f907-4eeb-4ca9-bd84-b447ea65a68c",
  "recovery": {
    "strategy": "none"
  },
  "field_errors": [
    {
      "path": ["orders", 1, "price_micro"],
      "code": "invalid_value",
      "message": "Invalid request value."
    }
  ]
}

Fix every indicated field and submit a new request. Do not send the same body again unchanged.

Follow recovery.strategy

Validate code before following any recovery instruction. If the code is unknown, do not honor an automatic action even when strategy is a familiar value such as retry or refresh_identity_token. Log the response and request_id, pause the affected mutation, reconcile its state, and update your client before continuing.

Treat an unknown strategy as none until your client understands it. This keeps a newly introduced recovery instruction from activating an unsafe retry.

check_status names the durable resource to read. For example:

{
  "code": "dependency_outcome_unknown",
  "recovery": {
    "strategy": "check_status",
    "resource": {
      "kind": "batch",
      "batch_hash": "0x51cda67500000000000000000000000000000000000000000000000000000000"
    }
  }
}

Read GET /trade/v1/batches/{batch_hash} until you know the existing submission's outcome. Creating another batch can duplicate or conflict with work that was already accepted.

Retry writes safely

An HTTP 429 means the request was rejected before the operation ran. Wait for Retry-After, then resending the same request is safe.

A timeout, TLS reset, or lost response is different: the server may already have accepted the write.

One clean order read is not proof that an ordinary timed-out placement was rejected; it can appear later. Follow the uncertain-submission recovery guide before resuming or placing a replacement.

Do not blanket-retry every 5xx. 502 dependency_invalid_response, for example, has recovery.strategy: "none"; the service returned data that could not safely be used. Follow the response's recovery value instead of deriving a retry policy from the status alone.

Accepted work can fail later

HTTP Problem Details means the request itself failed. A successful 202 or 201 can still represent asynchronous work that later reaches a terminal failure.

Orders, account batches, and wallet setup expose that state as failure:

{
  "status": "REJECTED",
  "failure": {
    "code": "post_only_would_cross",
    "title": "Post-only order would cross",
    "detail": "The order would execute immediately instead of resting.",
    "recovery": {
      "strategy": "none"
    }
  }
}

This embedded object deliberately has no HTTP status, type, or request_id: the read request succeeded, and the object describes the earlier operation. Use failure.code exactly as you use the code in an HTTP Problem Details body.

Common trading decisions

The API reference lists every status an endpoint can return, though not the individual codes behind each one. These are the codes a trading loop most often needs to distinguish:

For the complete API trading recovery flow, see Recovery.

Access and credentials

Authentication covers forbidden_scope and invalid_personal_access_token. These are the rest:

Endpoints that may not be available

Not every endpoint exists in every deployment, and a few have been withdrawn.

503 feature_not_configured says the same about a whole feature, such as account batches. Treat all of these as "not offered here" rather than as something to retry.

Reads that cannot be answered right now

A 425 means the request was understood but the answer does not exist yet. Wait and repeat it; the request itself is fine.

A 503 on these reads is a refusal, not a delay. Follow the recovery value rather than assuming every 503 is transient.

Resources that do not exist

A 404 ending in _not_found means the thing you named is not there, or is not visible to you: batch_not_found, category_not_found, event_not_found, group_not_found, market_not_found, order_not_found, profile_not_found, security_not_found, token_not_found, trading_day_not_found, and venue_not_found. Check the identifier before repeating the request.

422 price_feed_not_found is not one of these. The identifier can be perfectly valid; this deployment simply has no price source for it, so repeating the request will not help.

Origin and edge rate limits

Most failures come from the API origin and therefore include application/problem+json, X-Request-ID, and request_id in the body.

An edge rate limit happens before the request reaches the API. It uses application/json, carries the same stable rate_limited code and recovery, but has no request ID or account-bucket headers:

{
  "type": "urn:agara:problem:rate-limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "recovery": {
    "strategy": "retry_after",
    "after_seconds": 60
  }
}

See Rate limits for budgets and header examples.

WebSocket failures

WebSocket error frames use the same embedded failure object, plus an action that says whether to keep the connection, resubscribe one subject, or reconnect the whole socket. See Market stream errors for the frame and close-code contract.