error field:
Global Errors
These errors can occur on any authenticated endpoint.Unauthorized
Unauthorized/Invalid api key — Your API key is missing, expired, or invalid.
Ensure you’re sending all required authentication
headers.Unauthorized
Invalid L1 Request headers — Your L1 authentication headers (HMAC signature)
are malformed or the signature doesn’t match. See
Authentication.Service Unavailable
Trading is currently disabled. Check polymarket.com for updates — The
exchange is temporarily paused. No orders (including cancels) are accepted.Too Many Requests
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
Bad Request
Invalid token id — The token_id query parameter is missing or not a valid
token ID.Not Found
No orderbook exists for the requested token idPOST books
Bad Request
Invalid payload — The request body is malformed or missing required fields.Bad Request
Payload exceeds the limit — Too many token IDs in a single request. Reduce
the batch size.Pricing
Errors from price, midpoint, and spread endpoints.GET price
Bad Request
Invalid token id — The token_id parameter is missing or invalid.Bad Request
Invalid side — The side parameter must be BUY or SELL.Not Found
No orderbook exists for the requested token idPOST prices
Bad Request
Invalid payload — The request body is malformed or missing required fields.Bad Request
Invalid side — The side field must be BUY or SELL.Bad Request
Payload exceeds the limit — Too many token IDs in a single request.GET midpoint
Bad Request
Invalid token id — The token_id parameter is missing or invalid.Not Found
No orderbook exists for the requested token idPOST midpoints
Bad Request
Invalid payload — The request body is malformed or missing required fields.Bad Request
Payload exceeds the limit — Too many token IDs in a single request.GET spread
Bad Request
Invalid token id — The token_id parameter is missing or invalid.Not Found
No orderbook exists for the requested token idPOST spreads
Bad Request
Invalid payload — The request body is malformed or missing required fields.Bad Request
Payload exceeds the limit — Too many token IDs in a single request.Place Orders
Errors from order placement endpoints.POST order
Bad Request
Invalid order payload — The request body is malformed, missing required
fields, or contains invalid values.Bad Request
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.Bad Request
the order signer address has to be the address of the API KEYBad Request
'{address}' address banned — This address has been banned from trading.Bad Request
'{address}' address in closed only modeService Unavailable
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.Service Unavailable
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:
Bad Request
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.
Bad Request
invalid post-only order: order crosses book — A post-only (maker) order
would immediately match. Adjust the price so it rests on the book.Bad Request
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.Bad Request
order {id} is invalid. Size ({size}) lower than the minimum: {min} — The
order size is below the market minimum.Bad Request
order {id} is invalid. Duplicated.Bad Request
order {id} crosses the bookBad Request
not enough balance / allowance — Insufficient pUSD balance or token
allowance. Make sure the account holds enough pUSD and grant the exchange
allowances with Set Up Trading
Approvals.Bad Request
invalid expiration — The order expiration timestamp is in the past or
invalid.Bad Request
order canceled in the CTF exchange contractBad Request
order match delayed due to market conditionsBad Request
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.Bad Request
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.Bad Request
the market is not yet ready to process new ordersInternal Server Error
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.Too Early
The matching engine is restarting. Retry with exponential backoff. See
Matching Engine Restarts for restart handling.
Internal Server Error
there are no matching ordersInternal Server Error
FOK orders are filled or killed — A Fill-or-Kill order could not be fully
satisfied.Internal Server Error
the trade contains rounding issuesInternal Server Error
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
Bad Request
Invalid order payload — The request body is malformed.Bad Request
Invalid orderID — The provided order ID is not a valid format.DELETE orders
Bad Request
Invalid order payload — The request body is malformed.Bad Request
Too many orders in payload, max allowed: {N} — Too many order IDs in a
single cancellation request.Bad Request
Invalid orderID — One or more order IDs are not valid.DELETE cancel-market-orders
Bad Request
Invalid order payload — The request body is malformed or contains invalid
filter parameters.Query Orders
Errors from order query endpoints.GET order by ID
Bad Request
Invalid orderID — The order ID in the URL path is not valid.Internal Server Error
Internal server error — An unexpected error occurred while fetching the
order.GET orders
Bad Request
invalid order params payload — The query parameters are malformed or contain
invalid values.Internal Server Error
Internal server error — An unexpected error occurred while fetching orders.Trades
GET trades
Bad Request
Invalid trade params payload — The query parameters are malformed or contain
invalid values.Internal Server Error
Internal server error — An unexpected error occurred while fetching trades.GET last-trade-price
Bad Request
Invalid token id — The token_id parameter is missing or invalid.Internal Server Error
Internal server error — An unexpected error occurred while fetching the last
trade price.POST last-trades-prices
Bad Request
Invalid payload — The request body is malformed or missing required fields.Bad Request
Payload exceeds the limit — Too many token IDs in a single request.Markets
GET market by condition ID
Bad Request
Invalid market — The condition ID is not a valid format.Not Found
market not found — No market exists with this condition ID.GET tick-size
Bad Request
Invalid token id — The token ID is not valid.Not Found
market not found — No market found for this token ID.GET neg-risk
Bad Request
Invalid token id — The token ID is not valid.Not Found
market not found — No market found for this token ID.Price History
GET prices-history
Bad Request
Filter validation errors — One or more query parameters (
market, startTs,
endTs, fidelity) are invalid.GET ohlc
Bad Request
startTs is required — The startTs query parameter is missing.Bad Request
asset_id is required — The asset_id query parameter is missing.Bad Request
invalid fidelity: {val} — The fidelity parameter must be one of: 1m,
5m, 15m, 30m, 1h, 4h, 1d, 1w.Bad Request
limit cannot exceed 1000 — Reduce the limit parameter to 1000 or below.GET orderbook-history
Bad Request
startTs is required — The startTs query parameter is missing.Bad Request
either market or asset_id must be provided — You must specify either a
market (condition ID) or asset_id (token ID).Bad Request
limit cannot exceed 1000 — Reduce the limit parameter to 1000 or below.Authentication and API Keys
POST auth api-key
Unauthorized
Invalid L1 Request headers — L1 authentication headers are missing or
invalid.Bad Request
Could not create api keyGET auth api-keys
Internal Server Error
Could not retrieve API keys — An unexpected error occurred while fetching
your API keys.DELETE auth api-key
Internal Server Error
Could not delete API key — An unexpected error occurred while deleting the
API key.GET auth derive-api-key
Unauthorized
Invalid L1 Request headers — L1 authentication headers are missing or
invalid.Bad Request
Could not derive api key!Builder API Keys
POST auth builder-api-key
Internal Server Error
could not create builder api key — Builder API key creation failed.GET auth builder-api-key
Internal Server Error
could not get builder api keys — An unexpected error occurred while fetching
builder API keys.DELETE auth builder-api-key
Bad Request
invalid revoke builder api key body — The request body is malformed.Bad Request
invalid revoke builder api key headers — Required authentication headers are
missing.Internal Server Error
could not revoke the builder api key: {key} — An unexpected error occurred
while revoking the key.Builder Trades
GET builder trades
Bad Request
invalid builder trade params — The query parameters are malformed or contain
invalid values.Internal Server Error
could not fetch builder trades — An unexpected error occurred while fetching
builder trades.Balance and Allowance
GET balance-allowance
Bad Request
Invalid asset type — The asset_type parameter is not a recognized asset
type.Bad Request
Invalid signature_type — The signature_type parameter must be EOA,
POLY_PROXY, or GNOSIS_SAFE.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.