오류 및 속도 제한
Watch-IP의 모든 엔드포인트는 어떤 제품을 호출하든 동일한 형태로 오류를 반환하고 동일한 방식으로 속도 제한을 적용합니다.
오류 응답 형태
2xx가 아닌 응답은 항상 error(안정적인 기계 판독용 코드)와 message(사람이 읽을 수 있는 설명)를 담은 JSON 객체입니다. error는 API 버전 간에 변하지 않지만 message 텍스트는 바뀔 수 있으므로, message가 아니라 error를 기준으로 분기 처리하세요.
오류 응답
{
"error": "invalid_ip",
"message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}공통 상태 코드
각 엔드포인트가 반환할 수 있는 정확한 코드 집합은 해당 엔드포인트의 레퍼런스 페이지에 문서화되어 있습니다. 여기서는 API 전반에서 공통으로 사용되는 코드만 다룹니다.
- 400
- 잘못된 형식의 입력 — 유효하지 않은 IP 주소, 비어 있거나 크기가 초과된 배치(POST /v1/lookup은 최대 100개의 IP를 허용), 또는 필수 필드 누락.
- 401
- API 키가 없거나 유효하지 않습니다.
- 403
- 이 라우트에 맞지 않는 키 유형(시크릿 키 전용 엔드포인트에 공개 가능 키를 사용하거나 그 반대인 경우), 또는 — GET /v1/geo와 POST /v1/email/validate에 한해 — 키의 오리진 허용 목록에 없는 Origin/Referer인 경우입니다. 오리진 문제의 경우 CORS 헤더도 설정되지 않으므로, 이 본문과 무관하게 브라우저가 응답을 차단합니다.
- 422
- 의미상으로는 유효하지만 처리할 수 없는 입력 — 현재는 POST /v1/risk/check에서 제공된 IP를 위치로 확인할 수 없는 경우에만 발생합니다.
- 429
- 현재 1분 윈도우의 속도 제한을 초과했습니다.
속도 제한
속도 제한은 고정된 1분 단위 윈도우로 고객 계정별로 적용되며, 라우트별로 개별 추적되지 않고 호출하는 모든 엔드포인트에 걸쳐 공유됩니다. 이 제한은 항목 수가 아니라 HTTP 호출 수를 셉니다. POST /v1/lookup과 POST /v1/email/batch는 항목이 1개든 100개든 1건의 요청으로 계산되며, 이메일 목록 작업의 생성, 상태 조회, 결과 다운로드도 마찬가지입니다. 속도 제한으로 인한 429(error: "rate_limit_exceeded")에는 현재 윈도가 초기화될 때까지 남은 초를 알려 주는 Retry-After 헤더가 포함됩니다. 그 시간만큼 기다린 뒤 다시 시도하세요.
안전하게 재시도하기
GET /v1/geo, GET /v1/lookup/{ip}, POST /v1/lookup, POST /v1/email/validate는 읽기 전용이므로 네트워크 오류 직후 바로 재시도해도 안전합니다. POST /v1/risk/check는 기본적으로 저장된 기준값을 갱신합니다 — 기준값을 변경하지 않아야 하는 시험적 재시도가 필요하다면 먼저 commit:false를 전달하세요.