Errors - Tradara

Tradara uses standard HTTP status codes and a single JSON error envelope across every service. The envelope is defined in the shared common.yaml components and is identical for the Trading API and the Prop Firm API.

Error envelope

{
  "error": "human-readable description of what went wrong"
}

Some services include additional fields (code, details, request_id) when the failure has structured context. Always read error first; treat extra fields as optional.

Capture the X-Request-Id response header on every failed call. Tradara support uses it to find the matching gateway and service logs.

Status codes

Status	Meaning	Typical cause
`400 Bad Request`	Validation failure	Missing required field, malformed JSON, invalid enum value, wrong type
`401 Unauthorized`	Missing or invalid credentials	No `X-Tradara-Api-Key`, expired JWT, revoked key
`403 Forbidden`	Authenticated but not allowed	Firm key on a JWT-only route, cross-firm access, missing entitlement
`404 Not Found`	Resource does not exist or is not visible to the caller	Wrong `order_id`, `account_id` belongs to another firm
`409 Conflict`	State conflict	Idempotency key reuse with different body, order already cancelled, role already assigned
`422 Unprocessable Entity`	Risk or business-rule rejection	Margin breached, daily loss limit hit, instrument not tradable
`429 Too Many Requests`	Rate limit exceeded	See Rate limits
`500 Internal Server Error`	Unexpected server fault	Transient — retry with backoff
`502 Bad Gateway`	Upstream service unavailable	Downstream venue or internal service down
`503 Service Unavailable`	Service draining or in maintenance	Retry with backoff

Order-specific errors

POST /v1/orders and related order writes layer additional semantics on top of the generic codes:

Status	Meaning	Recovery
`400`	Field validation (e.g. `limit_price` missing for `LIMIT`)	Fix the request; do not retry as-is
`403`	Account not active, instrument not entitled, or firm halted	Check account status; respect emergency halt
`422`	Risk engine rejected (margin, max position, daily loss)	Surface to the user; resize or skip
`502`	Routing failed at the venue gateway	Safe to retry with the same `Idempotency-Key`

The order may also transition to REJECTED asynchronously after an initial 202 placement. Watch the order lifecycle stream for that state.

Retries

Retry 5xx and network failures with exponential backoff (start at 250 ms, cap at 30 s, jitter 50 %).
Retry POST /v1/orders only when you sent an Idempotency-Key. Reusing the same key returns the original response.
Do not retry 4xx other than 429 — the request will fail again until you fix it.
For 429, honour the Retry-After header.

Example: validation failure

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Request-Id: 5f8a2c0c-2d8c-4e3a-9f4a-6c1d2b8f3a11

{
  "error": "limit_price is required when execution_type is LIMIT"
}

Example: risk rejection

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Request-Id: 6d2a91f0-4f1d-4b6e-91c2-c5a7e9d3b210

{
  "error": "daily loss limit exceeded for account",
  "code": "RISK_DAILY_LOSS_LIMIT"
}

Example: upstream timeout

HTTP/1.1 502 Bad Gateway
Content-Type: application/json
X-Request-Id: 7e4b1a2c-9e0a-43c2-b9f3-8e6d4c1a0d22

{
  "error": "routing gateway did not respond in time"
}