Skip to main content
Air API 사용 중 발생하는 오류는 대부분 인증, 요청 형식, 크레딧, 서비스 상태 중 하나에 해당합니다. 아래에서 증상에 맞는 항목을 찾아 확인하세요.

​
오류 코드 빠른 참조

​
인증 오류

원인: 시크릿 키가 누락되었거나, 잘못된 키를 사용하고 있거나, 이미 삭제된 키입니다.확인 사항:
  • 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의 모델별 접근 권한 체계는 (내부에서 확인 필요)

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

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