Error reference
Every error the API returns, what causes it, and how to handle it in a bot.
| HTTP | Error | Cause | Bot handling |
|---|---|---|---|
| 400 | Missing required fields | ticker/action/yes_no/count absent | Fix the payload; do not retry as-is |
| 400 | Invalid or unknown market | Bad ticker/slug, or market settled | Re-resolve the market via search |
| 400 | Market is not tradable / not accepting orders | Venue paused books or market closed | Skip market; retry only after status change |
| 400 | count must be at least N | Below venue minimum order size (Polymarket: 5) | Raise size or skip |
| 400 | limit_price / trigger_price grid errors | Off the market's tick grid (0.01 or 0.001) | Round to the advertised min_tick_size |
| 400 | Insufficient liquidity | Displayed depth cannot absorb a market order | Reduce size or use IOC limit |
| 400 | Fill-or-kill / Immediate-or-cancel rejected | FOK couldn't fully fill; IOC had nothing marketable | Expected control flow — handle, don't alarm |
| 400 | Insufficient balance | Cost + resting reservations exceed available balance | Free reservations (cancel resting buys) or downsize |
| 400 | Insufficient open position | Selling/reserving more than held (minus holds) | Reconcile positions via GET /portfolio |
| 401 | Unauthorized | Missing/revoked API key | Stop; rotate credentials |
| 403 | Forbidden: account ownership mismatch | Key does not own the target account | Fix account/key pairing |
| 404 | Not found | Unknown order id / account / user | Treat as terminal for that id |
| 410 | Order already executed / not resting | Cancelling something that already completed | Treat as success-equivalent: nothing left to cancel |
| 429 | RateLimitExceeded | Per-minute token bucket empty | Back off per Retry-After |
| 429 | QuotaExceeded / RestingOrderLimitExceeded | Monthly quota or resting-order cap | Upgrade tier or reduce footprint |
| 500 | Internal Server Error | Our bug | Retry with the SAME client_order_id — idempotency makes it safe |
The golden rule
Always send client_order_id. Any timeout or 5xx can then be retried blindly: if the original write succeeded you get the stored order back with idempotent_replay: true; if it failed, the retry executes. Double-fills become impossible.