AI API 오류: 401, 403, 429, 5xx

AI API의 HTTP 상태 코드는 조사의 출발점이지 전체 원인이 아닙니다. 재시도 전에 요청 ID, UTC 시각, 엔드포인트, 모델, 키 이름, 선택 그룹, 구조화 오류, 시간을 보존하고 클라이언트, 인증, 접근 정책, 프로토콜, 라우팅, 모델 백엔드, downstream 연결 중 어느 계층에서 종료됐는지 찾습니다.

상태 코드의 첫 해석

상태	우선 의미	첫 조치
400	잘못된 payload 또는 프로토콜	수정하고 같은 내용으로 재시도하지 않기
401	키 누락, 오류, 비활성 또는 만료	Authorization과 현재 키 확인
403	계정, 모델, 그룹 또는 IP 정책	채널보다 키 제한 먼저 확인
404	경로나 모델 ID 오류	Base URL과 /v1/models 확인
429	할당량, 속도 또는 경로 제한	제한 계층을 찾고 제한된 backoff 사용
499	클라이언트가 완료 전 취소	deadline, Abort, 프록시, 첫 출력 확인
502/503/504	Upstream, 가용성 또는 시간 예산	증거를 보존하고 제한적으로 폴백 또는 재시도

계층별 진단

401은 보통 라우팅 전에 발생합니다. Authorization: Bearer ..., 키 상태, 호스트, 배포에 남은 이전 Secret을 확인하세요. 전체 키를 로그나 티켓에 넣지 마세요.

403은 공급자 거부 증거가 아닙니다. 모델 제한, IP allowlist, 그룹 권한, 계정 정책이 채널 선택 전에 작동할 수 있습니다. 같은 키로 /v1/models를 호출하고 정확한 오류 코드를 봅니다.

429에서는 키, 계정, 모델 그룹, 경로 중 제한 주체를 찾습니다. Retry-After를 따르고 jitter가 있는 지수 backoff를 사용하며 횟수, 총 시간, 동시성을 제한합니다. 키를 늘려도 계정 제한을 우회하지 못할 수 있습니다.

499는 downstream 연결 종료 기록입니다. Abort, 브라우저, CDN, 로드밸런서, 프록시에서 시작하고 첫 유효 출력을 비교합니다. 한 건만으로 채널 장애를 입증할 수 없습니다.

재시도 결정

• 잘못된 요청, 키, 접근: 원인을 수정하고 그대로 반복하지 않습니다.
• Rate Limit: 허용될 때만 제한된 backoff를 사용합니다.
• 일시적 502, 503, 504: 안전하게 반복 가능한 작업만 엄격한 예산으로 재시도합니다.
• 클라이언트 취소: 결과가 여전히 필요하고 중복 부작용이 없을 때만 반복합니다.
• 도구나 쓰기 작업: 애플리케이션 멱등성을 먼저 마련합니다.

각 시도는 작업과 비용을 만들 수 있습니다. ID, 시각, 엔드포인트, 스트리밍, 모델, 그룹, 상태, 코드, 시간은 안전하게 공유할 수 있지만 전체 키, 프롬프트, 응답, 원문 body, 이메일, 평문 IP는 제외합니다. 이후 라우팅 가이드와 스트리밍 가이드를 활용하세요.