GenderAPI.io V2 오류와 재시도

오류와 HTTP 상태 코드

애플리케이션 오류는 application/problem+json(RFC 9457)을 사용합니다. 사람이 읽는 detail이 아니라 안정적인 code와 action을 기준으로 분기하세요. 검증 오류에서는 errors에 JSON Pointer 위치가 포함됩니다. 지원팀에 문의할 때는 request_id를 함께 알려 주세요. 프록시나 전송 오류는 다른 본문을 반환할 수 있으므로 JSON을 파싱하기 전에 Content-Type을 확인하세요.

다음 합성 422 예시는 과금 전에 발견된 잘못된 이메일 구문을 보여 줍니다. 공개 오류 카탈로그에는 모든 코드, 상태, 설명과 권장 조치가 나와 있습니다.

{
  "type": "urn:genderapi:problem:validation_error",
  "title": "validation error",
  "status": 422,
  "detail": "A valid email address is required.",
  "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
  "code": "validation_error",
  "request_id": "11111111-1111-4111-8111-111111111111",
  "documentation": "https://api.genderapi.io/api/v2/errors",
  "action": "correct_request",
  "errors": [
    {
      "pointer": "/value",
      "message": "Invalid email address."
    }
  ],
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 0,
      "remaining_credits": null,
      "billing_status": "not_charged",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

• V2 전체 오류 카탈로그

오류 응답 필드

접근, 과금과 요청 메타데이터

재시도와 과금

같은 요청을 다시 보내는 경우를 포함해 모든 추정 요청은 새 작업입니다. 각 요청에는 일반 크레딧 규칙이 적용됩니다. 중복 요청 방지 기능이 없으므로 연결이 끊기거나 결과를 알 수 없을 때 자동으로 재시도하지 마세요.

429 응답을 받으면 Retry-After만큼 기다린 뒤 다음 요청을 보내세요. 추정 요청이 실패하면 먼저 code, action과 meta.usage.billing_status를 확인하세요. billing_reconciliation_required이거나 과금이 미확정이면 재시도하기 전에 request_id와 함께 지원팀에 문의하세요.

일부만 성공한 일괄 요청도 HTTP 200을 반환할 수 있습니다. 각 항목을 확인하고, 과금이 확정된 뒤 실패한 항목만 다시 제출하세요. 성공한 항목을 다시 제출하면 다시 과금됩니다.

X-Request-ID와 meta.request_id는 현재 HTTP 시도를 식별합니다. 현재 잔액은 /usage에서 확인하세요. HEAD는 과금되는 추정을 시작하지 않습니다. 추정 응답과 계정 응답은 캐시할 수 없습니다.

클라이언트는 응답에 필드가 추가되어도 처리할 수 있어야 하며, 정보가 없을 때의 null 값을 그대로 유지해야 합니다.

요청 한도

이 상한까지는 요청이 항상 받아들여진다고 가정하지 말고 HTTP 429와 Retry-After를 처리하세요. 서비스 용량은 공유됩니다. 표시된 값은 현재 서비스 기본값입니다. 요청 한도 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset(Unix 초)이 포함됩니다. Retry-After는 초 단위 대기 시간입니다. 이 헤더는 남은 크레딧이 아니라 요청 한도를 나타냅니다. 무료인 /usage 조회도 요청 한도에 포함됩니다.