요청 제한과 재시도

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

기본 요청 빈도 제한 없음

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`에 따라 요청(파라미터, 모델, 키, 잔액)을 고치세요.
네트워크 오류 / 시간 초과	채팅은 그냥 재시도하면 됩니다. 이미지와 영상은 먼저 호출 로그에서 작업이 만들어졌는지 확인한 뒤, 다시 제출할지 정하세요.

Python · 429와 5xx 재시도

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 그룹이나 고객 지원을 통해 사용량을 미리 알려 주세요. 그에 맞춰 용량을 늘려 드립니다.