오류 및 문제 해결

오류 원인과 HTTP 상태로 호출 문제를 찾고 안전한 복구 방법을 선택합니다.

API 요청이 실패하면 HTTP 상태 코드와 마스킹된 오류 정보를 먼저 보관한 후 요청, 인증, 모델 또는 서버 중 원인을 판단합니다. 원인을 확인하지 않은 채 같은 요청을 계속 재시도하지 않습니다.

자격 증명과 고객 데이터를 먼저 보호합니다

진단 기록에 전체 API 키, Authorization 또는 x-api-key Header, Cookie, 비밀번호, 전체 Prompt, 고객 파일 또는 기타 민감한 정보를 포함하지 않습니다.

오류 원인부터 판단

오류 원인	일반적인 현상	권장 조치
요청 내용	잘못된 JSON, 필드 누락, 매개변수 타입 오류 또는 파일 형식 불일치	오류 정보에 따라 요청을 수정하며 그대로 재시도하지 않습니다
인증 및 권한	API 키 누락, 무효 또는 대상 모델 접근 권한 없음	Base URL, 프로토콜의 인증 Header, 키 상태 및 모델 권한을 확인합니다
모델 및 리소스	모델 ID, 작업 ID 또는 요청 경로 없음	모델 목록에서 ID를 다시 복사하고 리소스 소유 계정을 확인합니다
플랫폼 또는 상위 서비스	일시적인 서비스 장애, 처리 시간 초과 또는 상위 서비스 오류	진단 정보를 보관하고 제한적으로 재시도하며 계속 실패하면 요청을 중지합니다
비동기 작업	제출 성공 후 작업 실패, 장시간 처리 중 또는 결과 사용 불가	원래 작업 상태부터 조회하며 작업을 바로 중복 생성하지 않습니다

하나의 실패에 여러 단서가 있을 수 있습니다. 예를 들어 404는 잘못된 엔드포인트 또는 존재하지 않는 모델이나 작업을 의미할 수 있으므로 최종 요청 URL과 오류 본문을 함께 확인해야 합니다.

HTTP 상태	일반적인 의미	권장 복구 방법
`400`	요청 형식, 매개변수 또는 입력 내용 오류	요청을 수정한 후 다시 보냅니다
`401`	API 키 누락, 무효 또는 API 요구 사항과 다른 인증 Header	프로토콜의 인증 방식을 확인하고 필요하면 새 키를 생성하여 교체합니다
`403`	계정, 키 또는 모델의 허용 범위가 요청을 충족하지 못함	계정 상태, 토큰 제한 및 모델 권한을 확인합니다
`404`	Base URL, 엔드포인트, 모델 또는 작업 없음	최종 URL, 모델 ID, 작업 ID 및 소유 계정을 확인합니다
`429`	요청 빈도, 동시 요청, 할당량 또는 서비스 용량 제한	잦은 요청을 중지하고 실제 오류에 따라 부하를 줄인 후 나중에 재시도합니다
`500`–`599`	플랫폼, 게이트웨이 또는 상위 서비스가 일시적으로 요청을 완료할 수 없음	진단 정보를 보관하고 제한된 횟수로 백오프 재시도합니다

이 상태는 진단 방향을 빠르게 정하는 데만 사용합니다. 프로토콜과 상위 서비스의 프로그램 오류 코드가 다를 수 있으므로 HTTP 상태, 실제 오류 본문 및 해당 API 레퍼런스로 원인을 판단해야 합니다.

프로그램 오류 코드와 처리 권장 사항은 오류 코드 레퍼런스를 확인합니다. 해결되지 않으면 Request ID와 FAQ를 참고합니다. 첫 연동 문제는 빠른 시작과 API 키, Base URL 및 인증을 다시 확인합니다.