# API v2 오류 및 재시도

> GenderAPI v2 Problem Details, 유효성 검사 오류, 요율 제한 및 청구 불확실성을 처리합니다. 재시도 비용 및 지원 문의 시기를 이해하세요.

Canonical HTML: https://www.genderapi.io/ko/docs/v2/errors-and-retries

Last reviewed: 2026-09-25

## 오류 및 HTTP 상태 코드

응용 프로그램 오류는 application/problem+json(RFC 9457)를 사용합니다. detail의 설명 텍스트 대신 안정적인 필드 code 및 action를 사용하여 오류를 처리합니다. 유효성 검사 오류의 경우 errors에는 영향을 받는 필드에 대한 JSON 포인터 위치가 포함되어 있습니다. 지원팀에 문의할 때 request_id를 포함하세요. 프록시 또는 연결 실패는 다른 응답 본문을 반환할 수 있습니다. JSON을 구문 분석하기 전에 Content-Type을 확인하세요.

다음 합성 422 예는 청구 전 잘못된 이메일 구문을 보여줍니다. 공개 오류 카탈로그에는 모든 코드, 상태, 설명 및 제안된 조치가 나열되어 있습니다.

| HTTP 상태 | 일반적인 의미 | 다음 단계 |
| --- | --- | --- |
| 400 / 413 / 415 | 잘못된 JSON, 너무 큰 본체 또는 지원되지 않는 미디어 유형. | 요청을 수정하세요. |
| 401 / 403 | 액세스가 거부되었거나 계정이 제한되었거나 크레딧이 부족합니다. | code를 검사하십시오. 올바른 액세스 또는 크레딧 보충/평가판 재설정을 기다립니다. |
| 422 | 입력이 잘못되었거나 옵션이 호환되지 않습니다. | errors에서 식별된 필드를 수정하십시오. |
| 404 / 405 | 알 수 없는 경로 또는 지원되지 않는 HTTP 방법입니다. | 엔드포인트 경로와 Allow 응답 헤더를 확인하세요. |
| 429 | 속도 또는 동시성 제한. | 다른 요청을 보내기 전에 Retry-After를 기다리십시오. |
| 500 | 예기치 않은 서버 오류가 발생했습니다. | request_id로 지원팀에 문의하세요. 다시 시도하기 전에 결제를 확인하세요. |
| 502 / 503 / 504 | 공급자, 종속성, 청구 또는 시간 초과 오류. | 재시도하기 전에 code, action 및 billing_status를 검사하세요. |

```json
{
  "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 오류 카탈로그](https://api.genderapi.io/api/v2/errors)

## 재시도 및 청구

모든 예측 요청은 다시 전송된 동일한 요청을 포함하여 새로운 작업입니다. 각 요청에는 일반적인 신용 규칙이 적용됩니다. 중복 요청 방지 기능이 없으므로 연결이 끊기거나 알 수 없는 결과가 발생한 후 자동 재시도를 피하세요.

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 읽기도 속도 제한에 포함됩니다.

| 한계 | 값 |
| --- | --- |
| JSON 요청 본문 | 64 KiB 최대 |
| 예측값 | 1~254자 |
| 일괄 | API 키가 포함된 항목 50개; 10(IP 평가판 포함) |
| 계좌 요율 | 분당 요청 120개 |
| IP 환율 | 분당 요청 600개 |
| 동시 작업 | 계정당 2개; 서비스 전반에 걸쳐 16개 |