How Tradeics APIs report failures and how clients should retry safely.
Envelope errors (REST V2)
{
"error": true,
"reason": "unauthorized",
"data": {}
}Use reason for branching — do not parse human message strings.
LLM proxy errors
OpenAI-style:
{
"error": {
"message": "Authentication Error, No api key passed in.",
"type": "auth_error",
"code": "401"
}
}Retry policy
| Status | Retry? | Guidance |
|---|---|---|
429 |
Yes | Exponential backoff + jitter |
500 / 502 / 503 |
Yes | Idempotent methods only |
400 / 401 / 403 / 404 / 422 |
No | Fix request or credentials |
Idempotency
- Prefer natural keys (
external_id) on upserts. - Do not double-post payments after timeouts — read payment status first.
- For LLM calls, treat completions as non-idempotent; store request ids if you need audit.
- Webhook consumers and MCP write tools must be idempotent — see Webhooks.