AI API 오류 가이드: 401, 403, 429, 5xx

AI API의 인증, 액세스 정책, 속도 제한, 클라이언트 취소, 공급사 장애를 진단하고 언제 재시도해도 안전한지 판단합니다.

AI API 오류 가이드: 401, 403, 429, 5xx

AI API 오류는 상태 코드를 원인 그 자체가 아니라 조사의 출발점으로 볼 때 가장 쉽게 진단할 수 있습니다. 재시도하기 전에 요청 ID, 타임스탬프, 엔드포인트, 모델, API 키 이름, 선택된 그룹, 응답 본문, 시간 정보를 보존하세요.

목표는 요청을 거부하거나 종료한 계층이 클라이언트, 인증, 액세스 정책, 프로토콜 검증, 라우팅, 모델 백엔드, 다운스트림 연결 중 어디인지 찾는 것입니다.

주요 상태 코드가 일반적으로 의미하는 것

상태 일차 해석 첫 조치
400 요청 형식, 필드 또는 프로토콜 계약이 올바르지 않음 선택한 엔드포인트와 페이로드를 비교하고, 그대로 재시도하지 않기
401 자격 증명이 없거나 형식이 잘못되었거나 비활성화·만료되었거나 유효하지 않음 Authorization 헤더와 현재 키 확인
403 인증은 되었지만 계정, 모델, 그룹, IP 또는 정책에 의해 차단됨 채널을 테스트하기 전에 키 제한과 모델·그룹 액세스 확인
404 엔드포인트 경로가 잘못되었거나 사용할 수 없는 모델 식별자 Base URL, 경로, 인증된 모델 목록 확인
429 요청 속도, 한도 또는 적격 경로의 제한 한도와 그룹 제한을 확인하고, 제한된 백오프나 설정된 폴백 사용
499 완료 전에 다운스트림 클라이언트의 연결이 끊기거나 취소됨 클라이언트 기한, 중단, 프록시, 첫 출력 시간 확인
500 내부 처리 또는 어댑터 오류 요청 ID를 보존하고, 작업이 안전한 경우에만 재시도
502/503 잘못된 공급사 응답, 사용할 수 없는 경로 또는 일시적인 용량 문제 경로 근거를 확인하고 제한된 폴백이나 재시도 사용
504 게이트웨이 또는 공급사의 시간 예산 만료 첫 출력 시간과 전체 시간을 클라이언트 기한과 비교

이 해석은 진단의 출발점입니다. 특정 호출의 실제 원인은 오류 본문과 요청 기록으로 판단합니다.

모델을 바꾸기 전에 401 진단하기

401은 대개 실질적인 모델 라우팅이 이루어지기 전에 발생합니다. 다음을 확인하세요.

  • 헤더가 Authorization: Bearer ... 형식을 사용하는지
  • 애플리케이션이 따옴표, 공백, 자리표시자 값을 함께 넣지 않았는지
  • 키가 활성화되어 있고 만료되지 않았는지
  • 요청이 의도한 Modelflare 호스트로 전송되는지
  • 시크릿 관리자나 배포 환경에 교체 전의 이전 키가 남아 있지 않은지

전체 키를 로그나 지원 문의에 붙여 넣지 마세요. 노출 가능성이 있다면 전용 테스트 키로 재현한 뒤, 유출된 자격 증명은 폐기하세요.

403은 먼저 액세스 정책 실패로 진단하기

403이 곧 공급사가 요청을 거부했다는 뜻은 아닙니다. 인증은 성공했더라도 다음과 같은 이유로 채널이 선택되기 전에 액세스가 거부될 수 있습니다.

  • 키가 요청한 모델을 제한하고 있습니다.
  • 키의 IP 허용 목록에 관측된 클라이언트 IP가 없습니다.
  • 계정이 선택된 모델 그룹을 사용할 수 없습니다.
  • 사용자나 키가 정책에 따라 비활성화되었습니다.
  • 요청한 기능이 해당 경로에서 허용되지 않습니다.

같은 키로 /v1/models를 조회하고, 키의 그룹 및 모델 제한을 확인한 뒤 정확한 오류 코드를 비교하세요. 채널이 선택되지 않았다면 공급사 채널을 바꿔도 그보다 앞선 정책 결정은 바뀌지 않습니다.

재시도 폭주 없이 429 진단하기

429는 용량이나 정책을 알리는 신호이지, 촘촘한 루프로 즉시 재시도하라는 지시가 아닙니다. 해당 제한이 키 한도, 계정, 모델 그룹, 선택된 경로 중 어디에 속하는지 먼저 파악하세요.

재시도할 수 있는 속도 제한이라면 다음을 따르세요.

  1. Retry-After가 있으면 그 값을 따릅니다.
  2. 지터를 적용한 지수 백오프를 사용합니다.
  3. 시도 횟수와 전체 경과 시간에 상한을 둡니다.
  4. 애플리케이션 동시성을 알려진 범위 안에서 유지합니다.
  5. 순서가 정해진 폴백 그룹은 요청한 모델과 프로토콜을 유지할 때만 사용합니다.

API 키를 더 만든다고 해서 계정 수준이나 그룹 수준의 요청 한도를 반드시 우회할 수 있는 것은 아닙니다.

499는 호출자부터 바깥쪽으로 진단하기

Modelflare는 응답이 완료되기 전에 다운스트림 클라이언트 연결이 끊기면 499를 기록할 수 있습니다. 호출자부터 확인하세요.

  • 중단 신호가 트리거되었습니까?
  • 클라이언트, 로드 밸런서, CDN, 리버스 프록시가 유휴 타임아웃이나 전체 타임아웃에 도달했습니까?
  • 사용자가 페이지를 닫거나 에이전트를 중지했습니까?
  • 스트림이 화면에 보이는 텍스트 없이 도구 이벤트만 생성했습니까?
  • 첫 유효 출력까지 얼마나 걸렸습니까?

499 기록만으로는 채널 장애가 입증되지 않습니다. 라우팅 정책을 바꾸기 전에 같은 시간대, 같은 모델·그룹의 다른 요청과 비교하세요.

5xx 실패를 계층별로 구분하기

5xx의 경우 클라이언트에서 모든 실패를 일반적인 500으로 바꾸지 말고 원래 상태와 오류 세부 정보를 보존하세요.

  • 검증이나 어댑터에서 발생한 500은 결정적일 수 있어서, 요청을 바꾸지 않으면 다시 실패할 수 있습니다.
  • 502는 공급사 응답이 잘못되었거나 불완전하다는 뜻일 수 있습니다.
  • 503은 적격한 경로가 없거나 일시적으로 사용할 수 없다는 뜻일 수 있습니다.
  • 504는 시간 예산이 만료되었다는 뜻이지만, 어느 계층에서 만료되었는지는 따로 확인해야 합니다.

요청 시간, 선택된 그룹, 지원팀이 확인할 수 있는 채널 근거, 비슷한 시점의 다른 요청을 활용해 일회성 응답 오류와 지속적인 경로 문제를 구분하세요.

재시도 여부 결정하기

실패 유형 기본 재시도 판단
잘못된 페이로드 또는 지원하지 않는 프로토콜 요청을 수정하고, 그대로 재시도하지 않음
유효하지 않은 키 또는 액세스 거부 자격 증명이나 정책을 수정하고, 그대로 재시도하지 않음
한도 소진 의도적으로 한도를 늘리거나 재배분하고, 반복 재시도하지 않음
속도 제한 허용되는 경우 제한된 백오프로 재시도
일시적인 502/503/504 멱등한 작업만 엄격한 시도 예산 안에서 재시도
클라이언트 취소 사용자가 여전히 결과를 원하고 중복이 안전한 경우에만 재시도
도구 또는 쓰기 부작용 반복하기 전에 애플리케이션 수준의 멱등성 확보

재시도는 새 작업을 만들고 새로운 비용을 발생시킬 수 있습니다. 모든 시도를 기록하고, 나중에 성공한 결과 때문에 원래 실패가 가려지지 않도록 하세요.

안전하게 수집할 근거

지원 문의나 장애 검토를 위해 다음을 수집하세요.

  • 요청 ID와 UTC 타임스탬프
  • 엔드포인트와 스트리밍 모드
  • 요청한 모델과 선택된 그룹
  • HTTP 상태와 구조화된 오류 코드
  • 전체 시간과 첫 유효 출력 시간
  • 호출자가 취소했는지 여부
  • 도구나 이미지 입력처럼 요청에 사용된 기능을 민감 정보 없이 설명한 내용

승인된 보안 절차에서 명시적으로 요구하지 않는 한 전체 API 키, 프롬프트, 응답 내용, 원본 요청 본문, 이메일, 평문 IP 주소는 포함하지 마세요.

실패한 계층을 찾은 뒤 폴백 설계는 안정적인 AI API 라우팅을, 이벤트와 타임아웃 관련 실패는 스트리밍 가이드를 참고하세요.

자주 묻는 질문

403은 공급사 장애를 증명합니까?

아닙니다. 403은 공급사 경로가 선택되기 전에 계정, 키, 모델, 그룹, IP 또는 기능 정책 때문에 발생할 수 있습니다. 먼저 요청 기록과 오류 코드를 확인하세요.

499는 일반적인 공급사 모델 오류입니까?

아닙니다. Modelflare 요청 기록에서 499는 완료 전에 관측된 다운스트림 취소를 나타냅니다. 모델 장애로 판단하기 전에 호출자와 프록시의 기한을 조사하세요.

모든 5xx 응답을 재시도해야 합니까?

아닙니다. 반복해도 안전한 작업만 재시도하고, 시도 횟수와 시간 예산에 상한을 두며, 첫 번째 오류를 보존하세요. 결정적인 어댑터 문제나 요청 문제는 반복해도 나아지지 않습니다.