공식 문서
문제 해결 매뉴얼HTTP 상태 코드운영 및 유지 관리 가이드
更新于 2026-11-18 · 约 5 分钟读完
대형 모델 API 공통 HTTP 상태 코드(401/402/403/429/529) 빠른 문제 해결 매뉴얼
OpenAI, Anthropic Claude 및 Gemini 인터페이스를 호출할 때 일반적인 HTTP 상태 코드 의미, 위치 지정 방법 및 클라이언트 재시도 모범 사례에 대한 포괄적인 요약입니다.
상태코드 간편체크리스트
| HTTP 상태 코드 | 오류 분류 | 핵심 이유 | 권장 솔루션 |
|---|---|---|---|
400 Bad Request | 요청 형식 오류 | JSON 필드가 잘못되었거나, max_tokens가 상한을 초과했거나, 프로토콜이 잘못 선택되었습니다. | 엔드포인트 프로토콜 확인(예: Claude의 기본 매개변수가 /v1/messages로 전송됨) |
401 Unauthorized | 신원 인증 실패 | sk-... 키의 철자가 틀리거나 비활성화되었거나 요청 헤더가 누락되었습니다 | [로그인 없이 키 생존성 테스트] 바로가기(/check) 원클릭 키 유효성 검증 |
402 / 403 Forbidden | 할당량 또는 권한이 제한되어 있습니다 | 계정 잔액이 부족하고, 하위 키 할당량이 소진되었으며, IP가 화이트리스트에 없거나 그룹에 모델이 포함되어 있지 않습니다 | 콘솔 잔액, 하위 키 할당량 진행 표시줄 및 바인딩 그룹 확인 |
429 Too Many Requests | 속도 또는 동시 전류 제한 | 계정의 최대 동시 채널 수를 초과하거나 하위 키의 5시간/일 롤링 제한을 트리거 | 클라이언트에서 지수 백오프 재시도를 활성화하거나 콘솔에서 속도 제한 정책을 늘리세요 |
502 / 503 / 529 | 순간적인 상류 정체 | 공식 업스트림 컴퓨팅 성능이 최고조에 달하는 기간 동안의 순간적인 지터 | 게이트웨이에는 밀리초 수준의 자동 재해 복구 전환 기능이 내장되어 있으며 클라이언트는 |
콘솔에서 특정 오류 세부정보를 보는 방법은 무엇입니까?
개발자 콘솔에 로그인한 후 왼쪽 메뉴 "📜 통화 요금 → 비정상적인 요청 문제 해결"을 클릭하면 타임스탬프, 대상 모델, HTTP 상태 코드 및 최근 200개가 아닌 요청의 특정 오류 요약을 맹목적인 추측 없이 직접 볼 수 있습니다.
프로덕션 환경 SDK 지수 백오프 재시도 코드 예시
python
from openai import OpenAI
# 官方 SDK 默认自带 max_retries=2 指数退避,生产环境建议设为 3
client = OpenAI(
base_url="https://suptoken.ai/v1",
api_key="sk-your-key",
max_retries=3,
timeout=120.0,
)
🚀 准备好在项目中极速接入了吗?
注册即可创建专属 API Key,原生直连 Claude 4.5、GPT-5 Codex 与 Gemini 2.5 Pro。