API Integration
Error Handling
How the V3 gateway reports errors, and where asynchronous trade failures surface.
HTTP errors
The gateway returns standard HTTP status codes. The TypeScript SDK throws a FetchError for any response with status ≥ 300:
try {
await sdk.core.trade.open(body);
} catch (err) {
// FetchError { message, statusText, status }
}Common statuses:
| Status | Meaning |
|---|---|
400 | Validation error, malformed body, invalid basket configuration, or an unknown/inactive clientId. |
401 | Missing or invalid credentials (no/expired token, or an unknown x-api-key). |
403 | Not permitted, missing the required role, or the x-trade-account-id isn't yours. |
404 | Resource not found (position, order, trade account). |
429 | Rate limited, retry after the Retry-After header. |
503 | Maintenance mode. |
Asynchronous trade outcomes
POST /trade/open and the other execution endpoints are asynchronous. The HTTP response is an acknowledgement, it returns an execution whose status starts at IDLE. Success or failure arrives over the WebSocket:
execution.completed, the trade filled;position.created/position.updatedfollow.execution.failed, the trade failed; the event carries the reason.
Do not infer "no order was placed" from an ambiguous HTTP response. Reconcile with GET /executions/:id and GET /positions before retrying.