Polymarket API 오류: 모든 코드 해설

모든 Polymarket CLOB API 오류는 같은 형태, 즉 error 필드 하나로 이루어진 JSON 객체로 반환됩니다. 감탄할 만큼 일관적이지만, 방금 주문이 왜 사라졌는지 알아내려 할 때는 전혀 도움이 되지 않습니다.

{
  "error": "<message>"
}

이 페이지에서 그것들을 해설합니다. 문서화된 CLOB 오류, 상태 코드와 그 실제 원인, 그리고 공식 문서에서는 찾을 수 없는 부분인, Polymarket이 한 번도 문서로 남긴 적 없지만 프로덕션에서 실제로 마주치는 오류를 다룹니다.

문서화된 각 메시지에는 원인과 재시도 여부 판단을 담은 별도 페이지도 있으며, Polymarket 오류 색인에 정리되어 있습니다.

상태 코드 빠른 참조

401: 인증 오류

Unauthorized/Invalid api key

가장 많이 검색되는 Polymarket 오류입니다. API 키가 누락되었거나, 만료되었거나, 유효하지 않다는 뜻입니다. 실제로는 정말 잘못된 키인 경우가 거의 없으며, 대개 다음 중 하나입니다:

1. 자격 증명 세트의 일부만 보내고 있습니다. Polymarket L2 인증에는 키, 시크릿, 패스프레이즈가 함께 필요합니다. 흔한 실패는 POLY_API_KEY와 POLY_PASSPHRASE는 채우고 시크릿은 비워 두는 경우입니다. 클라이언트는 형식은 올바르지만 서명할 수 없는 요청을 보냅니다.
2. 시스템 시계가 어긋났습니다. 서명에는 타임스탬프가 포함되며, 시계가 몇 초 이상 어긋나면 서버가 무효로 거부하는 서명이 만들어집니다. 사람들이 가장 마지막에 찾아내는 원인이며, VM과 컨테이너에서 안타까울 만큼 흔합니다.
3. 거래하는 지갑과 다른 지갑으로 키를 파생했습니다. 키는 그것을 생성한 서명자 주소에 묶여 있습니다.
4. L2가 필요한 인증 엔드포인트에 L1 헤더를 보내고 있거나, 그 반대입니다.

Invalid L1 Request headers

L1 인증 헤더(EIP-712 서명 세트)의 형식이 잘못되었거나, 서명이 주장하는 주소와 일치하지 않습니다. 헤더의 주소와 같은 개인 키로 서명하고 있는지, 도메인 구분자가 사용 중인 체인(Polygon, 체인 ID 137)과 일치하는지 확인하세요. 잘못된 체인 ID에 대해 유효한 서명도 여전히 유효한 서명이지만, 이 서버에 대해서는 아닙니다.

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

"polymarket unable to generate api credentials"라는 검색어 뒤에 있는 오류들입니다. 둘 다 키 생성이나 파생이 실패할 때 인증 엔드포인트에서 반환됩니다. GET /auth/derive-api-key에서 Could not 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
}

문서에 없는 오류들

실제 디버깅 시간의 대부분이 여기에 들어갑니다. 다음 오류들은 CLOB 애플리케이션에서 발생하지 않기 때문에 Polymarket 오류 코드 레퍼런스에 나오지 않습니다. 엣지, 네트워크, 또는 클라이언트 라이브러리에서 발생합니다. 어느 계층이 오류를 만들었는지 알면 어디를 봐야 할지 알 수 있습니다.

"The server was unable to process your request"

문서에 없는 Polymarket 오류 중 가장 많이 검색되는 것입니다. CLOB API 오류가 아니라 엣지 계층 메시지이며, 요청이 애플리케이션에 도달하지 못했거나 애플리케이션에서 깔끔하게 돌아오지 못했을 때 받게 됩니다. 실제로 흔한 원인은 다음과 같습니다:

• 엣지가 라우팅 전에 거부하는 잘못된 형식의 요청: 너무 큰 페이로드, 잘못된 헤더, 또는 해당 경로에 맞지 않는 HTTP 메서드.
• 일시적인 업스트림 장애: 서비스가 재배포 중이거나 부하를 받고 있을 때.
• 지속적인 요청 한도 초과. Cloudflare는 거부하지 않고 대기열에 넣어 속도를 늦추므로, 한도를 크게 초과한 클라이언트는 깔끔한 429 대신 엣지에서 타임아웃되는 요청을 받게 될 수 있습니다.

백오프로 재시도할 수 있는 오류로 취급하되, 가끔이 아니라 지속적으로 발생한다면 먼저 요청 속도를 확인하고(요청 한도 레퍼런스 참고) 그 다음 페이로드 크기를 확인하세요.

403 Forbidden

Polymarket의 403은 대개 인증 문제가 아니며, 그래서 혼란스럽습니다. 일반적으로 엣지가 요청을 차단한 것입니다. 흔한 원인은 거래 엔드포인트에 대한 지역 제한, 데이터센터 및 VPN IP 대역에 대한 챌린지, 그리고 엣지가 클라이언트에서 올 것으로 기대하는 요청에 헤더가 없거나 브라우저와 다른 헤더가 있는 경우입니다.

403이 노트북에서는 안 나오고 클라우드 VM에서만 나온다면 코드 문제가 아니라 IP 평판 문제입니다. 마켓 데이터 엔드포인트에서는 안 나오고 거래 엔드포인트에서만 나온다면 지역 문제입니다.

SSL, TLS, 인증서 오류

"polymarket ssl error", "polymarket certificate error", "polymarket https error"는 거의 항상 클라이언트 측 문제입니다. Polymarket의 인증서는 정상이고, 여러분과 Polymarket 사이의 무언가가 문제입니다. 다음 순서로 확인하세요. 오래된 CA 번들(오래된 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을 팔지 않으므로, 호가 요청은 아무것도 반환하지 않습니다. 저희 데이터를 보면 이는 흔한 일입니다. BTC 5분 마켓 표본에서 8,510개 중 1,454개가 만기 60초 전에 한쪽 매도 호가가 비어 있었습니다.

오류가 아니라 "마켓 없음"으로 처리하세요. 거래를 건너뛰고, 촘촘한 루프로 재시도하지 마세요. 거래하는 시리즈에서 이런 일이 얼마나 자주 일어나는지 알고 싶다면 마켓 데이터 페이지에서 타임프레임별 유동성을 확인할 수 있습니다.

클라이언트 라이브러리 예외

PolyApiException[status_code=None, error_message=request exception!] 같은 오류는 서버가 아니라 Python 클라이언트에서 발생합니다. status_code=None이 단서입니다. HTTP 응답을 한 번도 받지 못했다는 뜻이므로, DNS, TLS, 타임아웃, 끊긴 소켓 같은 연결 수준의 실패가 라이브러리 예외로 나타난 것입니다. API 문제가 아니라 네트워크 문제로 디버깅하세요. relayer 클라이언트의 BuilderApiKeyCreds invalid authorization 401에도 같은 논리가 적용됩니다. 클라이언트에 전달된 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를 반환하는 것은 토큰 ID가 올바르더라도 마켓이 정산되면 Polymarket이 오더북 제공을 중단하기 때문입니다.

이런 벽에 부딪히고 있다면 연동을 디버깅하는 것이 아니라 데이터 소스가 빠져 있는 것입니다. PolyTest는 Polymarket 암호화폐 Up/Down 마켓이 진행되는 동안 전체 오더북 깊이를 포함한 특정 시점 스냅샷을 기록하므로, 결과 확정 후에도 기록이 남아 있습니다. 저희 오류 레퍼런스는 PolyTest API의 오류 형태를 다루며, 비교하자면 일부러 지루하게 만들었습니다.