오류 코드
PolyTest API는 표준 HTTP 상태 코드를 사용합니다. 모든 오류 응답은 문제를 설명하는 error 필드가 포함된 JSON 본문을 반환합니다.
오류 응답 형식: 모든 오류는 사람이 읽을 수 있는 메시지가 담긴
"error" 키 하나로 이루어진 JSON 객체를 반환합니다. HTTP 상태 코드는 오류 범주를 나타냅니다.400Bad Request
요청 형식이 잘못되었거나 필수 파라미터가 누락되었습니다.
{ "error": "timestamp query parameter is required" }주요 원인
- 필수 쿼리 파라미터 누락
- 잘못된 파라미터 형식 (예: ISO 8601이 아닌 타임스탬프)
- 허용 범위를 벗어난 잘못된 파라미터 값
401Unauthorized
인증 실패. 요청에 유효한 자격 증명이 없습니다.
{ "error": "Invalid API key" }주요 원인
- X-API-Key 헤더 또는 Authorization 헤더 누락
- API 키가 존재하지 않거나 유효하지 않음
- API 키가 폐기됨
- API 키가 만료됨
- JWT 토큰이 유효하지 않거나 만료됨
403Forbidden
자격 증명은 유효하지만 이 작업에 대한 권한이 없습니다.
{ "error": "Admin access required" }주요 원인
- 관리자 권한 없이 관리자 전용 엔드포인트(sync, seed)에 접근 시도
- API 키 범위에 필요한 권한이 포함되어 있지 않음
404Not Found
요청한 리소스가 존재하지 않습니다.
{ "error": "Market not found" }주요 원인
- 마켓 ID가 존재하지 않음
- 마켓 슬러그와 일치하는 레코드가 없음
- 주어진 타임스탬프 기준 ±2초 이내에 스냅샷이 없음
429Too Many Requests
요청 한도를 초과했습니다. 잠시 멈춘 뒤 안내된 시간 이후에 재시도하세요.
{ "error": "Rate limit exceeded" }주요 원인
- 플랜 등급의 분당 요청 한도 초과
- 버스트 한도 초과 (짧은 시간에 너무 많은 요청)
500Internal Server Error
서버에서 예기치 않은 오류가 발생했습니다. 드문 경우이며, 계속 발생하면 지원팀에 문의하세요.
{ "error": "Internal server error" }주요 원인
- 데이터베이스 연결 문제
- 업스트림 서비스 장애
- 예기치 않은 서버 측 예외
오류 처리
클라이언트 오류 (4xx)
자동으로 재시도하지 마세요. 재시도하기 전에 요청 파라미터나 인증을 수정하거나 리소스가 존재하는지 확인하세요.
서버 오류 (5xx)
지수 백오프로 안전하게 재시도할 수 있습니다. 1초 지연으로 시작해 시도할 때마다 두 배로 늘리며 최대 3회 재시도하세요.
import time
import requests
def api_request(url, headers, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 429:
wait = int(response.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait)
continue
if response.status_code >= 500:
time.sleep(2 ** attempt)
continue
return response
raise Exception("Max retries exceeded")