Ошибки API Polymarket: расшифровка каждого кода

Каждая ошибка CLOB API Polymarket возвращается в одном и том же виде — JSON-объект с единственным полем error. Это восхитительно единообразно и совершенно бесполезно, когда вы пытаетесь понять, куда только что исчез ваш ордер.

{
  "error": "<message>"
}

Эта страница их расшифровывает. Здесь — задокументированные ошибки CLOB, коды статуса и их настоящие причины, а также то, чего вы не найдёте в официальной документации: ошибки, с которыми люди реально сталкиваются в продакшене и которые Polymarket так и не описал.

У каждого задокументированного сообщения также есть своя страница с причинами и рекомендацией по повтору — они перечислены в указателе ошибок Polymarket.

Краткий справочник по кодам статуса

401 — ошибки аутентификации

Unauthorized/Invalid api key

Самая часто ищущаяся ошибка Polymarket. Ваш API-ключ отсутствует, истёк или недействителен. На практике это почти никогда не действительно плохой ключ — обычно дело в одном из этих пунктов:

1. Вы отправляете только часть набора учётных данных. Аутентификации L2 в Polymarket нужны ключ, секрет и passphrase вместе. Частая ошибка — заполнить POLY_API_KEY и POLY_PASSPHRASE, но не задать секрет: клиент отправляет корректно сформированный, но не поддающийся подписи запрос.
2. Системные часы рассинхронизировались. Подпись включает метку времени, и часы, отстающие больше чем на несколько секунд, дают подпись, которую сервер отклоняет как недействительную. Эту причину находят последней, и она удручающе часто встречается на виртуальных машинах и в контейнерах.
3. Вы получили ключ для другого кошелька, а не того, с которого торгуете. Ключи привязаны к адресу подписанта, который их создал.
4. Вы обращаетесь к аутентифицированному эндпоинту с заголовками L1 там, где ожидается L2, или наоборот.

Invalid L1 Request headers

Ваши заголовки аутентификации L1 — набор подписи EIP-712 — сформированы неверно, или подпись не соответствует адресу, который вы указываете. Проверьте, что подписываете тем же приватным ключом, что и адрес в заголовке, и что разделитель домена соответствует вашей сети (Polygon, chain ID 137). Подпись, действительная для неверного chain ID, остаётся действительной подписью — просто не для этого сервера.

Could not create api key / Could not derive api key!

Именно эти ошибки стоят за поисковым запросом «polymarket unable to generate api credentials». Обе возвращаются эндпоинтами аутентификации, когда создание или получение ключа не удаётся. Could not derive api key! на GET /auth/derive-api-key обычно означает, что для этого подписанта ключа ещё нет: derive возвращает существующий ключ, а не создаёт новый. Сначала создайте ключ через POST /auth/api-key, а при последующих запусках получайте его через derive.

400 — ошибки отклонения ордеров

Они возвращаются, когда ордер проходит транспортную проверку, но нарушает бизнес-правила. Они появляются в теле ответа POST /order и POST /orders.

425 — Too Early

Необычный код статуса, который сбивает с толку, потому что в остальном вебе его почти не используют. В Polymarket он означает, что механизм сопоставления перезапускается. Ваш запрос пришёл в тот момент, когда биржа снова поднимается.

Эта ошибка действительно временная, и её действительно безопасно повторять — пожалуй, это самая подходящая для повтора ошибка на платформе. Подождите и попробуйте снова; не считайте это сбоем и не поднимайте тревогу из-за единичного случая.

503 — биржа в ограниченном режиме

Polymarket может переводить биржу в ограниченные режимы. Это не сбои на вашей стороне, и сколько ни повторяй тот же запрос, это не поможет, пока режим не снимут.

Режим post-only стоит обработать как следует, потому что он точно говорит, когда возвращаться. Ответ содержит code: "post_only_mode" и retry_after_seconds, а та же задержка передаётся в заголовке Retry-After.

{
  "error": "post-only mode: only post-only orders and cancels are allowed",
  "code": "post_only_mode",
  "retry_after_seconds": 79
}

Ошибки, которых нет в документации

Именно на них уходит большая часть реального времени отладки. Следующих ошибок нет в справочнике кодов ошибок Polymarket, потому что они вообще не исходят от приложения CLOB — они приходят с edge, из сети или из вашей клиентской библиотеки. Знание того, какой слой породил ошибку, подсказывает, где искать.

"The server was unable to process your request"

Самая часто ищущаяся ошибка Polymarket, которой нет в документации. Это сообщение слоя edge, а не ошибка CLOB API: вы получаете его, когда запрос так и не дошёл до приложения или не вернулся из него без проблем. На практике обычные причины такие:

• Некорректный запрос, который edge отклоняет до маршрутизации — слишком большая полезная нагрузка, плохой заголовок или недопустимый HTTP-метод для маршрута.
• Временный сбой вышестоящего сервиса во время повторного развёртывания или под нагрузкой.
• Длительное превышение лимита запросов. Поскольку Cloudflare ограничивает скорость, ставя запросы в очередь, а не отклоняя их, клиент, сильно превышающий лимит, может получать таймауты на edge вместо чистого 429.

Считайте её повторяемой с отступом, но если она постоянная, а не эпизодическая, сначала проверьте частоту запросов — см. справочник по лимитам запросов, — а затем размер полезной нагрузки.

403 Forbidden

403 от Polymarket обычно не связан с аутентификацией, и именно это сбивает с толку. Как правило, это edge блокирует запрос. Частые причины — географические ограничения на торговых эндпоинтах, проверки для IP-диапазонов дата-центров и VPN, а также отсутствующие или не похожие на браузерные заголовки в запросах, которые edge ожидает от клиента.

Если 403 появляется только с вашей облачной виртуальной машины, но не с ноутбука, это проблема репутации IP, а не кода. Если он появляется на торговых эндпоинтах, но не на эндпоинтах рыночных данных, причина географическая.

Ошибки SSL, TLS и сертификатов

«polymarket ssl error», «polymarket certificate error» и «polymarket https error» почти всегда возникают на стороне клиента. С сертификатами Polymarket всё в порядке; не в порядке что-то между вами и ними. Проверьте по порядку: устаревший набор корневых сертификатов (очень часто встречается в старых Docker-образах и замороженных окружениях Python), корпоративный прокси с инспекцией TLS, подставляющий собственный сертификат, и системные часы, отстающие настолько, что сертификаты кажутся ещё не действительными или истёкшими.

# 1. Does TLS work at all, outside your app's HTTP client?
curl -sS -o /dev/null -w "%{http_code} %{ssl_verify_result}\n" \
  https://clob.polymarket.com/ok

# 2. Is your CA bundle current? (Python)
python3 -c "import certifi, os; print(certifi.where()); print(os.path.getmtime(certifi.where()))"

# 3. Is your clock right? Certificate validation depends on it.
date -u

"Service not ready"

Сообщение о стадии запуска: сервис уже достаточно поднялся, чтобы ответить, но ещё не готов обслуживать. По сути обрабатывайте его как 425 — подождите и повторите. Оно должно пройти за секунды, и исправить его на стороне клиента нельзя.

"Order manager not ready"

Сообщение о стадии запуска от механизма сопоставления, близкий родственник 425 Too Early. Сервис доступен, но слой управления ордерами ещё не до конца поднялся, поэтому он примет ваше соединение и откажет вашему ордеру. Ошибка временная, её безопасно повторять с отступом, — но воспринимайте её как сигнал прекратить отправку на несколько секунд, а не долбить сервер, потому что перезапуск обычно означает, что стакан вот-вот изменится у вас под ногами.

Если вы видите её постоянно, а не всплесками, проверьте статус Polymarket, прежде чем отлаживать собственный код, — на стороне клиента исправлять нечего.

"Couldn't get a quote"

Обычно означает, что на стороне, для которой вы запросили цену, нет ликвидности в стакане, а не что что-то сломалось. На тонких рынках Up/Down перед экспирацией одна сторона регулярно пустеет — никто не продаёт Up ни по какой цене, когда Up уже предрешён, — поэтому запрос котировки ничего не возвращает. Наши собственные данные показывают, что это обычное дело: в выборке 5-минутных рынков BTC у 1,454 из 8,510 за 60 секунд до экспирации на одной из сторон был пустой стакан аск.

Обрабатывайте это как «нет рынка», а не как ошибку: пропустите сделку и не повторяйте в плотном цикле. Если нужно знать, как часто это случается в серии, которой вы торгуете, страницы рыночных данных показывают ликвидность по таймфреймам.

Исключения клиентской библиотеки

Ошибки вроде PolyApiException[status_code=None, error_message=request exception!] приходят из Python-клиента, а не с сервера. Подсказка — status_code=None: HTTP-ответ так и не был получен, значит, это сбой на уровне соединения — DNS, TLS, таймаут или оборванный сокет, — который всплывает как исключение библиотеки. Отлаживайте это как сетевую проблему, а не как проблему API. То же рассуждение относится к BuilderApiKeyCreds invalid authorization 401 в клиенте relayer: это значит, что переданные клиенту учётные данные builder не были приняты; получите их заново, а не используйте закешированный набор.

Политика повторов, которая справляется со всем этим

Практический вывод: ошибки Polymarket делятся на три группы, и их смешение делает ботов хрупкими: повторять вслепую, повторять после конкретной задержки и никогда не повторять.

type Decision =
  | { retry: true; delayMs: number }
  | { retry: false; reason: string };

function classify(status: number, body: { error?: string; code?: string; retry_after_seconds?: number }, attempt: number): Decision {
  const msg = (body.error ?? "").toLowerCase();
  const backoff = Math.min(2 ** attempt * 250, 8000);
  const jittered = Math.random() * backoff;

  // Never retry — the request itself is wrong.
  if (status === 401) return { retry: false, reason: "auth: check key, secret, passphrase and clock drift" };
  if (status === 404) return { retry: false, reason: "not found" };
  if (status === 400) return { retry: false, reason: `validation: ${body.error}` };

  // Mode-restricted — the server tells you when to come back.
  if (status === 503 && body.code === "post_only_mode") {
    return { retry: true, delayMs: (body.retry_after_seconds ?? 60) * 1000 };
  }
  if (status === 503) return { retry: false, reason: "exchange paused or cancel-only" };

  // Transient — safe to retry.
  if (status === 425 || status === 429 || status >= 500) return { retry: true, delayMs: jittered };
  if (msg.includes("service not ready")) return { retry: true, delayMs: jittered };

  return { retry: false, reason: `unhandled status ${status}` };
}

Ошибки, из которых не выбраться отладкой

Некоторые вещи, похожие на ошибки, просто не поддерживаются. У Polymarket нет эндпоинта исторического стакана, так что неправильно вызывать нечего. Стакан разрешившегося рынка возвращает 404, потому что Polymarket перестаёт его отдавать после расчёта по рынку, даже если ваш ID токена в порядке.

Если вы упираетесь в эти стены, вы не отлаживаете интеграцию — вам не хватает источника данных. PolyTest записывает снимки крипторынков Polymarket Up/Down на конкретный момент времени, пока они работают, с полной глубиной стакана, так что история остаётся и после разрешения. Наш собственный справочник по ошибкам описывает форматы ошибок API PolyTest, которые на этом фоне намеренно скучны.