Error responses

#HTTP status codes

Code	Meaning
`200`	Success
`400`	Query validation failed, or the request is inconsistent
`404`	Resource does not exist
`429`	Rate limit exceeded
`500`	Server error

#Response envelope

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": [
    "outcomeId must be a string",
    "outcomeId should not be empty"
  ]
}

Field	Description
`statusCode`	The same number as the HTTP status
`error`	A short human-readable label (`"Bad Request"`, `"Not Found"`). Absent on `429` and `500`.
`message`	string or string[]. Query-validation failures are an array; errors raised by a handler (a missing `outcomeId` on the order book, a market that does not exist) are a single string.

message can be an array

Validation failures from the request validator come as message: string[]. Don't just show error.message as a single line — render each element of the array separately.

#A pattern for handling it on the client

type ApiError = {
  statusCode: number;
  error?: string;
  message: string | string[];
};
 
async function call() {
  const res = await fetch(url, init);
  if (!res.ok) {
    const err = (await res.json()) as ApiError;
    const messages = Array.isArray(err.message) ? err.message : [err.message];
    throw new Error(messages.join('\n'));
  }
  return res.json();
}

#Common scenarios

Situation	Response
`outcomeId` missing on the order book	400 + `"outcomeId is required"`
`outcomeId` missing on price history	400 + `["outcomeId must be a string", "outcomeId should not be empty"]`
Invalid enum value	400 + `["status must be one of the following values: ACTIVE, RESOLVED, CANCELLED"]`
Unknown query parameter	400 + `["property foo should not exist"]`
Market not found	404 + `"Market not found: <id or slug>"`
Outcome not found	404 + `"Outcome not found"`
Outcome from another market	400 + `"Outcome does not belong to this market"`
Rate limit	429 + `"ThrottlerException: Too Many Requests"` (no `error` field)

#Rate limit

Public endpoints are rate-limited per IP — see Rate limits for the current numbers.

If you get a 429, retry after a short backoff (a few seconds). If you're persistently blocked, consult the Retry-After header.

#Next

Pagination — the list envelope on successful responses
REST → Markets — the actual endpoints

Was this page helpful?