메인 콘텐츠로 건너뛰기
Air API 사용 중 발생하는 오류는 대부분 인증, 요청 형식, 크레딧, 서비스 상태 중 하나에 해당합니다. 아래에서 증상에 맞는 항목을 찾아 확인하세요.

​
오류 코드 빠른 참조

코드의미주요 원인
401Unauthorized시크릿 키가 없거나 유효하지 않음
402Payment Required크레딧 소진
403Forbidden해당 모델에 대한 접근 권한 없음
408Request Timeout요청 처리 시간 초과
422Unprocessable Entity요청 파라미터 형식 오류
429Too Many Requests요청 한도 초과 (Rate limit)
502Bad Gateway모델 서비스 일시 오류
503Service Unavailable서비스 점검 또는 과부하

​
인증 오류

원인: 시크릿 키가 누락되었거나, 잘못된 키를 사용하고 있거나, 이미 삭제된 키입니다.확인 사항:
  • Authorization: Bearer YOUR_API_KEY 헤더가 요청에 포함되어 있는지 확인하세요.
  • 키 앞뒤에 공백이 없는지 확인하세요.
  • 환경 변수에서 키를 불러오는 경우, 실제로 값이 주입되고 있는지 확인하세요.
  • 콘솔에서 해당 키가 아직 유효한 상태인지 확인하세요.
시크릿 키는 발급 시 한 번만 확인할 수 있으며, 이후에는 다시 조회할 수 없습니다.콘솔에서 기존 키를 삭제하고 새 키를 발급받으세요. 발급 즉시 복사해 환경 변수에 안전하게 보관하는 것을 권장합니다.

​
크레딧 / 과금 오류

원인: 조직의 AU 잔액이 0 이하로 소진되어 API 호출이 차단된 상태입니다.해결 방법:
  • 콘솔 Billing 페이지에서 AU를 충전하세요.
  • 충전 후 API 호출을 다시 시도하면 바로 재개됩니다.
  • 반복적인 크레딧 소진을 방지하려면 자동 충전(Auto Top-up)을 설정해두세요.
크레딧 소진 시 정확히 어떤 오류 메시지가 반환되는지는 (내부에서 확인 필요)

​
요청 형식 오류

원인: 요청 본문의 파라미터 타입이나 필드명이 올바르지 않습니다.확인 사항:
  • messages 배열에 role과 content 필드가 모두 포함되어 있는지 확인하세요.
  • temperature, max_tokens 등 숫자 파라미터에 문자열이 들어가지 않았는지 확인하세요.
  • API 레퍼런스에서 각 파라미터의 허용 범위를 확인하세요.
원인: model 파라미터에 입력한 ID가 실제 모델 ID와 다릅니다.해결 방법:
  • 콘솔에서 코드 보기를 클릭하면 해당 모델의 정확한 모델 ID가 포함된 코드 샘플을 확인할 수 있습니다. 이 값을 그대로 복사해 사용하세요.

​
Rate Limit / 서비스 오류

원인: 단시간에 너무 많은 요청을 보내 허용 한도를 초과했습니다.해결 방법:
  • 응답 헤더의 Retry-After 값을 확인하고 해당 시간(초) 이후에 재시도하세요.
  • 요청을 일정 간격으로 분산하거나 지수 백오프(exponential backoff)를 적용하세요.
Air API의 모델별 RPM/TPM 한도는 (내부에서 확인 필요)
원인: 모델 응답 생성에 설정된 제한 시간을 초과했습니다. 긴 max_tokens 값이나 복잡한 입력에서 발생할 수 있습니다.해결 방법:
  • max_tokens 값을 줄여 응답 길이를 제한하세요.
  • 클라이언트 측 timeout 설정이 너무 짧지 않은지 확인하세요.
  • 잠시 후 재시도하세요.
원인: 모델 서비스가 일시적으로 응답하지 않거나 점검 중입니다. RunPod, OpenRouter 등 주요 클라우드 API에서도 공통으로 발생하는 오류입니다.해결 방법:
  • 수 초~수 분 후 재시도하세요.
  • 동일한 오류가 지속된다면 문의 및 피드백 채널로 알려주세요.
AirCloud 서비스 상태 페이지 URL은 (내부에서 확인 필요)
원인: 모델 부하, 입력 길이, 또는 max_tokens 설정에 따라 응답 시간이 길어질 수 있습니다.확인 사항:
  • max_tokens 값을 필요한 만큼만 설정하세요.
  • Playground에서 동일한 입력으로 응답 속도를 먼저 확인하세요.
  • 지연이 지속된다면 다른 모델(예: 더 작은 파라미터 모델)로 전환을 검토하세요.

​
Playground 오류

아래 항목을 순서대로 확인하세요.
  1. 브라우저를 새로고침한 뒤 다시 시도하세요.
  2. 올바른 프로젝트와 모델이 선택되어 있는지 확인하세요.
  3. 크레딧 잔액이 충분한지 확인하세요.
  4. 시크릿 브라우저 모드나 다른 브라우저에서 시도해보세요.
Embedding 모델은 Playground를 지원하지 않습니다. API 호출로만 사용할 수 있으며, 이는 정상적인 동작입니다.코드 예시는 API 호출 방법 페이지를 참고하세요.

​
모델 관련

지원 모델은 지속적으로 추가되고 있습니다. 필요한 모델이 목록에 없는 경우 문의 및 피드백 채널을 통해 요청할 수 있습니다.
원인: 현재 계정 또는 프로젝트에서 해당 모델에 대한 접근 권한이 없습니다.
Air API의 모델별 접근 권한 체계는 (내부에서 확인 필요)

​
여전히 해결되지 않는 경우

위 항목으로 해결되지 않으면 문의 및 피드백 페이지를 통해 지원을 요청하세요. 오류 코드, 요청 내용, 발생 시각을 함께 전달하면 빠른 처리에 도움이 됩니다.