# 요청 제한과 재시도

계정과 키별 제한, 모든 회선이 가득 찼을 때의 응답, 그리고 올바른 재시도와 시간 초과 설정 방법.

> https://nezhagate.com/ko/docs/guide/rate-limits

## 기본 요청 빈도 제한 없음

NezhaGate는 계정별 요청 빈도에 기본 제한을 두지 않으며, 처리 용량도 사용량에 맞춰 늘어납니다. 사용량을 제한하려면 키마다 따로 한도를 설정하세요.

## 키별 제한

콘솔의 「API Keys」 페이지에서 키마다 설정합니다. 비워 두거나 0을 넣으면 제한이 없습니다:

| 설정 항목 | 역할 | 초과 시 응답 |
| --- | --- | --- |
| **분당 요청 수** | 이 키가 1분 동안 보낼 수 있는 최대 요청 수. | `429` `rate_limit_exceeded` |
| **일일 예산** | 이 키가 하루(UTC 기준)에 쓸 수 있는 최대 금액(미국 달러). | `402` `insufficient_quota` |
| **총 사용 한도** | 이 키가 통틀어 쓸 수 있는 최대 금액(미국 달러). 자동화에 맡긴 키가 폭주하지 않게 막을 때 좋습니다. | `402` `insufficient_quota` |
| **모델 허용 목록** | 이 키는 목록에 있는 모델만 호출할 수 있습니다. | `403` `permission_denied` |
| **IP 허용 목록** | 목록에 있는 IP 또는 IP 대역에서 온 요청만 받습니다. | `403` `permission_denied` |

## 모든 회선이 가득 찼을 때

- 각 모델은 여러 회선으로 제공되며, 게이트웨이가 요청을 회선에 자동으로 나눠 보냅니다. 한 모델의 모든 회선이 동시에 가득 차면 429가 돌아오며, OpenAI 호환 엔드포인트는 기다릴 초를 `Retry-After` 헤더로 알려 줍니다.

- 이미지와 영상 작업은 회선이 가득 차도 거절되지 않습니다. 대기열에서 기다리다가(`status`가 `queued`이며 대기 순번과 예상 대기 시간이 함께 옵니다) 차례가 되면 자동으로 시작됩니다.

- 기간 한정 무료 모델에는 하루 호출 횟수 한도도 있습니다. 한도를 넘으면 UTC 0시에 초기화될 때까지 429가 돌아옵니다.

## 언제 재시도하나요

| HTTP | 조치 |
| --- | --- |
| **429** | `Retry-After` 헤더의 초만큼 기다린 뒤 재시도하세요. 헤더가 없으면 1초, 2초, 4초로 간격을 늘려 가며 기다리세요. |
| **500 / 502 / 503 / 504** | 지수 백오프(1초, 2초, 4초, 8초에 약간의 무작위 지연을 더함)로 재시도하세요. 보통 3~5회면 충분합니다. 이런 실패는 과금되지 않습니다. |
| **기타 4xx** | 그대로 다시 보내도 소용없습니다. 먼저 `error.code`에 따라 요청(파라미터, 모델, 키, 잔액)을 고치세요. |
| **네트워크 오류 / 시간 초과** | 채팅은 그냥 재시도하면 됩니다. 이미지와 영상은 먼저 호출 로그에서 작업이 만들어졌는지 확인한 뒤, 다시 제출할지 정하세요. |

```
import random
import time
import requests

def post_with_retry(url, headers, payload, tries=5):
    for attempt in range(tries):
        r = requests.post(url, headers=headers, json=payload, timeout=600)
        if r.status_code == 429:
            time.sleep(float(r.headers.get("Retry-After", 2 ** attempt)))
            continue
        if r.status_code >= 500:
            time.sleep(2 ** attempt + random.random())     # 1, 2, 4, 8 s ... plus jitter
            continue
        return r                                           # 2xx, or a 4xx to fix in the request
    return r
```

## 시간 초과

- 비스트리밍 요청 하나는 약 10분까지 실행될 수 있으며, 그 이상이면 앞단 게이트웨이가 연결을 끊습니다(HTTP 524). 긴 답변이나 추론 모델에는 `stream: true`를 쓰세요.

- 클라이언트의 시간 초과는 최소 10분으로 설정하세요. 그렇지 않으면 긴 답변이 오기 전에 클라이언트 쪽에서 먼저 포기합니다.

- 이미지와 영상은 비동기 작업이라 제출 요청이 금방 응답하므로, 이 제한이 적용되지 않습니다.

## 더 많은 용량이 필요하다면

높은 동시 요청을 꾸준히 쓰려면 [Telegram 그룹](https://t.me/+-erBoH9-AYY4MTM1)이나 고객 지원을 통해 사용량을 미리 알려 주세요. 그에 맞춰 용량을 늘려 드립니다.