error field:
Global Errors
These errors can occur on any authenticated endpoint.Unauthorized/Invalid api key — Your API key is missing, expired, or invalid.
Ensure you’re sending all required authentication
headers.Invalid L1 Request headers — Your L1 authentication headers (HMAC signature)
are malformed or the signature doesn’t match. See
Authentication.Trading is currently disabled. Check polymarket.com for updates — The
exchange is temporarily paused. No orders (including cancels) are accepted.Too Many Requests — You’ve exceeded the rate
limit. Back off and retry with exponential
backoff.Order Book
Errors from the order book endpoints.GET book
POST books
Payload exceeds the limit — Too many outcome IDs in a single request. Reduce
the batch size.Pricing
Errors from price, midpoint, and spread endpoints.GET price
POST prices
GET midpoint
POST midpoints
GET spread
POST spreads
Place Orders
Errors from order placement endpoints.POST order
Invalid order payload — The request body is malformed, missing required
fields, or contains invalid values.the order owner has to be the owner of the API KEY — The maker address in
the order doesn’t match the address associated with your API key.Trading is currently cancel-only. New orders are not accepted, but cancels are allowed. — The exchange is in cancel-only mode. You can cancel existing
orders but cannot place new orders.post-only mode: only post-only orders and cancels are allowed — The exchange
is in post-only mode. You can cancel orders and place orders with postOnly: true; non-post-only orders are rejected. The response includes code: "post_only_mode" and retry_after_seconds, and the same retry delay is also
sent in the Retry-After HTTP header.Retry-After HTTP header.
POST orders
All errors fromPOST /order apply, plus:
Too many orders in payload: {N}, max allowed: {M} — The batch contains more
orders than the maximum allowed per request.200 response array, with individual error messages for each failed order.
In post-only mode, non-post-only orders in a batch return per-order errors:
Order Processing Errors
These errors are returned when an order passes initial validation but fails during processing. They appear in the response body ofPOST /order and POST /orders.
invalid post-only order: order crosses book — A post-only (maker) order
would immediately match. Adjust the price so it rests on the book.order {id} is invalid. Price ({price}) breaks minimum tick size rule: {tick}
— The order price doesn’t align with the market’s tick size. Use GET /tick-size to check the valid tick
size.order {id} is invalid. Size ({size}) lower than the minimum: {min} — The
order size is below the market minimum.not enough balance / allowance — Insufficient pUSD balance or token
allowance. Make sure the account holds enough pUSD and grant the trading
approvals with Set Up Trading
Approvals. An allowance error
names one missing spender at a time. If it names the Neg Risk Adapter
(0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296), the account wallet is missing
the adapter approvals required for CTF negative-risk markets.order couldn't be fully filled. FOK orders are fully filled or killed. — A
Fill-or-Kill order could not be completely filled by available liquidity. The
entire order is rejected.no orders found to match with FAK order. FAK orders are partially filled or killed if no match is found. — A Fill-and-Kill order found no matching orders
at all. At least one match is required.order timed out — The exchange could not process the order before the
request deadline. This typically happens during bursts of concurrent order
submissions from the same account. The order was rejected before reaching the
order book and can be safely resubmitted.Matching Engine Errors
Internal matching engine errors that may surface during order execution.The matching engine is restarting. Retry with exponential backoff. See
Matching Engine Restarts for restart handling.
FOK orders are filled or killed — A Fill-or-Kill order could not be fully
satisfied.the price of the taker's order has a discrepancy greater than allowed with the worst maker orderCancel Orders
Errors from order cancellation endpoints.DELETE order
DELETE orders
Too many orders in payload, max allowed: {N} — Too many order IDs in a
single cancellation request.DELETE cancel-market-orders
Invalid order payload — The request body is malformed or contains invalid
filter parameters.Query Orders
Errors from order query endpoints.GET order by ID
GET orders
invalid order params payload — The query parameters are malformed or contain
invalid values.Trades
GET trades
Invalid trade params payload — The query parameters are malformed or contain
invalid values.GET last-trade-price
Internal server error — An unexpected error occurred while fetching the last
trade price.POST last-trades-prices
Markets
GET market by condition ID
GET tick-size
GET neg-risk
Price History
GET prices-history
Filter validation errors — One or more query parameters (
market, startTs,
endTs, fidelity) are invalid.GET ohlc
invalid fidelity: {val} — The fidelity parameter must be one of: 1m,
5m, 15m, 30m, 1h, 4h, 1d, 1w.Authentication and API Keys
POST auth api-key
GET auth api-keys
Could not retrieve API keys — An unexpected error occurred while fetching
your API keys.DELETE auth api-key
Could not delete API key — An unexpected error occurred while deleting the
API key.GET auth derive-api-key
Builder API Keys
POST auth builder-api-key
GET auth builder-api-key
could not get builder api keys — An unexpected error occurred while fetching
builder API keys.DELETE auth builder-api-key
could not revoke the builder api key: {key} — An unexpected error occurred
while revoking the key.Builder Trades
GET builder trades
invalid builder trade params — The query parameters are malformed or contain
invalid values.could not fetch builder trades — An unexpected error occurred while fetching
builder trades.Balance and Allowance
GET balance-allowance
Invalid signature_type — The signature_type parameter must be 0 (EOA),
1 (POLY_PROXY), 2 (POLY_GNOSIS_SAFE) or 3 (POLY_1271, Deposit Wallet).Status Code Reference
The CLOB API has an internal override: any error message containing
"not found" returns 404, "unauthorized" returns 401, and "context canceled" returns 400, regardless of the original status code.