Polymarket error codes and fixes

이 가이드는 UI와 API에서 자주 보이는 Polymarket 오류 코드가 무엇인지, 왜 발생하는지, 그리고 구체적인 해결 방법을 설명합니다. 통합, 주문 흐름, 또는 지갑 연결을 디버그할 때 문제를 빠르게 진단하는 데 도움이 됩니다.

핵심 요약

• Polymarket 오류는 주로 몇 가지 범주에 속합니다: 지오블로킹(403), API 검증(422), 속도 제한, CLOB/거래 인증, 지갑 또는 pUSD 자금 문제, 그리고 CTF/CTF 작업 오류.
• Gamma 목록 호출에서는 커서 기반 페이지네이션(after_cursor)을 사용하세요 — offset는 HTTP 422로 거부됩니다.
• CLOB는 거래 시 API 키 + HMAC을 요구합니다; 읽기는 인증이 필요 없습니다.
• 많은 UI의 "order rejected" 사례는 지갑 배포, pUSD 부족, 승인, 틱 사이즈 변경, 또는 FAK 부분 체결로 인해 발생합니다 — Relayer 흐름과 CLOB 주문 응답을 확인하세요.

오류가 중요한 이유(간단히)

예측 시장 흐름의 오류는 주문 차단, 부분 체결, 또는 정산 지연을 초래할 수 있습니다. Polymarket은 여러 표면(Gamma, Data, CLOB, Market WebSocket)을 사용합니다. 어느 표면에서 오류가 발생했는지 알면 해결 범위를 좁힐 수 있습니다.

H2: 일반적인 API 및 WebSocket 오류 패턴

Gamma (https://gamma-api.polymarket.com)

• 증상: offset으로 마켓을 페이지네이션할 때 HTTP 422.
  • 이유: Gamma는 키셋(keyset) 페이지네이션을 사용합니다. offset는 거부됩니다.
  • 해결: 이전 호출이 반환한 next_cursor를 사용해 after_cursor를 사용하세요. 예시:

curl 'https://gamma-api.polymarket.com/markets?limit=100&after_cursor=eyJpZCI6Ij...' \
  -H 'Accept: application/json'

• 증상: 과부하 시 429 유사 동작(스로틀링) 또는 예측 불가능한 5xx.
  • 이유: Gamma는 엔드포인트별 속도 제한을 시행합니다(예: /markets에 한도가 있음).
  • 해결: 문서화된 한도를 준수하고 지수적 재시도(exponential retry)를 적용하세요. 요청을 통합하고 가능한 경우 limit을 최대 1000까지 늘리세요.

Data API (https://data-api.polymarket.com)

• 포지션, 트레이드, 오픈인터레스트 같은 일반 조회는 공개입니다; 인증 실패가 보이면 정확한 베이스 URL과 헤더를 확인하세요.

CLOB (https://clob.polymarket.com)

• 증상: 거래 엔드포인트에서 주문 배치가 인증 오류로 거부됨.
  • 이유: 거래용 엔드포인트는 API 키와 HMAC 서명을 요구합니다. 읽기(오더북, 중간값, 가격 이력)는 공개입니다.
  • 해결: CLOB 명세에 따라 요청을 생성하고 서명하세요. 쓰기 작업을 시도하기 전에 먼저 읽기 요청으로 테스트하세요.

Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market)

• 증상: 연결이 닫히거나 실시간 이벤트가 수신되지 않음.
  • 이유: 소켓은 10초마다 PING을 기대합니다; 서버는 유휴 연결을 종료할 수 있습니다. 또한 연결당 최대 500개 계측기(instrument)를 구독할 수 있습니다.
  • 해결: 요구되는 PING을 전송하고, 500개를 초과하면 구독을 여러 연결로 분할하세요.

H2: 지오블록과 HTTP 403 (Polymarket geoblock 403)

• 증상: 주문을 시도하거나 트레이딩 라우트에 접근할 때 HTTP 403. UI가 지오블록 메시지를 반환함.
  • 이유: Polymarket은 IP 기반으로 특정 관할구역에서 주문 배치를 차단합니다. 일부 지역은 완전 차단이고, 일부는 닫기 전용(close-only)입니다.
  • 해결: IP 위치를 확인하세요. 차단된 관할구역에 있다면 Polymarket의 공식 자격 지침을 따르세요. VPN을 이용한 우회는 서비스 약관 위반입니다. 차단이 오류라고 생각하면 공식 사이트를 통해 Polymarket 지원에 연결 진단과 IP 증거를 제공해 문의하세요.

H2: 일반적인 "order rejected" 원인과 해결

1. 지갑이 아직 배포되지 않았거나 프록시가 없음

• 증상: Relayer 흐름 중 배포 또는 프록시 오류로 주문 실패.
• 이유: Polymarket은 두 가지 지갑 유형을 지원합니다; Safe가 아닌 사용자는 첫 거래 시 프록시가 배포됩니다.
• 해결: Relayer가 지갑 배포 흐름을 완료하게 두세요. 트랜잭션 완료 후 주문을 재시도하세요.

2. pUSD 또는 토큰 부족

• 증상: 잔액 부족으로 주문 거부.
• 이유: 거래는 pUSD가 필요합니다.
• 해결: 계정을 pUSD로 충전하세요(Polymarket의 안내 참조). 지갑에서 토큰 컨트랙트와 잔액을 확인하세요.

3. ERC-20 승인과 Relayer 흐름

• 증상: 승인 대기 중 주문이 정체됨.
• 이유: Relayer는 승인 단계를 가스리스로 처리할 수 있지만, 지갑 흐름이 완료되어야 합니다.
• 해결: Relayer 요청이 완료되었는지 확인하고 지갑 UI에서 대기 중인 확인 사항이 없는지 확인하세요.

4. 틱 사이즈 및 최소 증분 실패

• 증상: 주문이 거부되거나 예상치 못하게 반올림됨; 작은 가격 차이는 허용되지 않음.
• 이유: Polymarket은 틱 사이즈를 강제합니다(대개 $0.01, 극단 구간에서는 $0.001로 조여짐).
• 해결: 활성 틱에 맞춰 가격과 수량을 반올림하세요. Market WebSocket의 tick_size_change를 구독해 변화를 감지하세요.

5. FAK / 시장 주문의 부분 체결 및 슬리피지

• 증상: 시장 주문이 부분 체결되거나 취소된 것처럼 보임.
• 이유: CLOB 헬퍼는 FAK(Fill-And-Kill)를 사용합니다. 슬리피지 보호 내에서 완전히 체결되지 않으면 잔여분은 취소됩니다.
• 해결: createMarketOrder 응답에서 체결된 수량을 확인하고 부분 체결을 프로그래밍적으로 처리하세요.

6. 수수료 또는 카테고리 관련 거부

• 증상: 수수료 관련 오류로 주문 실패.
• 이유: 테이커 수수료는 카테고리별로 달라집니다(현재 0%–1.8%); Builder가 추가 베이시스 포인트를 적용할 수 있습니다.
• 해결: 마켓 카테고리와 Builder를 사용하는 경우 귀하의 귀속(attribution) 헤더를 확인하세요. 비용 계산에 테이커 수수료를 포함했는지 확인하세요.

H2: CTF 작업 및 정산 오류

• 증상: split/merge/redeem이 실패하거나 오류 반환.
• 이유: CTF는 ERC-1155 결과 토큰 프레임워크입니다; pUSD, 토큰 부족 또는 오라클 결의가 분쟁 상태이면 작업이 실패할 수 있습니다.
• 해결: 잔액을 확인하고 UMA 결의가 완료되었는지 확인하세요. UMA 분쟁이 정산을 일시중지하면 UMA가 최종화될 때까지 기다리세요.

H2: 문제 해결 체크리스트(빠른 런북)

• 오류를 보고한 표면(Gamma, Data, CLOB, 또는 WebSocket)을 확인하세요.
• 쓰기 전에 최소 실패 요청(GET 오더북 또는 GET 마켓)을 재현하세요.
• 지갑 상태 확인: 프록시 배포 여부, pUSD 잔액, 대기 중인 Relayer 트랜잭션.
• 틱 사이즈를 검증하고 입력을 그에 맞게 반올림하세요.
• 페이지네이션 오류가 있으면 Gamma에서 after_cursor로 전환하세요.
• 속도 제한을 준수하고 429/5xx 응답 시 백오프하세요.

거래 또는 통합에 미치는 영향

주문을 차단하는 오류는 대기 시간을 증가시키고 실행 품질을 떨어뜨립니다. 방어적인 클라이언트 로직을 구축하세요: 부분 체결을 감지하고, 사용자에게 명확한 오류 메시지를 표시하며, 안전한 재시도를 위해 충분한 상태를 영속화하세요. CLOB를 통해 주문을 라우팅하는 Builder인 경우 귀속 헤더와 API 키/HMAC이 올바른지 확인해 예기치 않은 거부를 방지하세요.

마무리

Polymarket 오류 코드는 대개 몇 가지 근본 원인을 가리킵니다: 지오블로킹, 페이지네이션/속도 제한, 거래용 인증, 지갑/Relayer 상태, 틱 사이즈 제약, 잔액 부족. 오류가 발생하면 표면을 식별하고 원시 응답을 캡처한 다음 위 체크리스트를 따르세요. Polymarket의 공개 API와 WebSocket 엔드포인트는 주요 진단 표면입니다; 거기서부터 시작하세요.

자주 묻는 질문

Gamma에서 마켓 페이지네이션 시 HTTP 422가 발생하는 이유는 무엇인가요?

Gamma는 키셋 페이지네이션을 사용합니다. API는 offset을 HTTP 422로 거부합니다. 이전 호출이 반환한 after_cursor 값과 limit 파라미터를 사용하세요.

Polymarket geoblock 403은 무엇을 의미하며 어떻게 해결하나요?

403 지오블록은 귀하의 IP가 Polymarket이 주문 배치를 제한하는 관할구역에 있음을 의미합니다. IP 위치를 확인하고 Polymarket의 공식 자격 안내를 따르세요. 차단을 우회하기 위해 VPN을 사용하지 마세요; 오류라고 생각되면 지원에 문의하세요.

시장 주문이 부분 체결되거나 취소된 이유는 무엇인가요?

CLOB 헬퍼는 기본적으로 FAK(Fill-And-Kill) 주문을 배치합니다. 유동성이 주문을 완전히 매칭하지 못했거나 슬리피지 보호가 작동하면 잔여분은 취소됩니다. 주문 응답을 검사해 체결된 수량을 확인하고 보수적으로 재시도하세요.

가격 증분 때문에 주문이 거부되는 이유는 무엇인가요?

Polymarket은 틱 사이즈를 강제합니다(일반적으로 $0.01, 극단 구간에서는 $0.001로 조여짐). 가격이나 수량이 더 작은 증분을 사용하면 주문이 거부되거나 반올림됩니다. Market WebSocket에서 tick_size_change를 구독해 최신 상태를 유지하세요.

오더북을 읽거나 Market WebSocket을 사용하려면 API 키가 필요한가요?

아니요. CLOB 읽기(오더북, 중간값, 가격 이력)와 Market WebSocket은 공개입니다. CLOB의 거래 엔드포인트는 API 키와 HMAC이 필요합니다; Gamma와 Data REST API는 공개 읽기입니다.