> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aieev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 문제 해결

> Air API 사용 중 자주 발생하는 오류와 해결 방법

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

## 오류 코드 빠른 참조

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

***

## 인증 오류

<AccordionGroup>
  <Accordion title="401 Unauthorized — API 키가 유효하지 않습니다">
    **원인:** 시크릿 키가 누락되었거나, 잘못된 키를 사용하고 있거나, 이미 삭제된 키입니다.

    **확인 사항:**

    * `Authorization: Bearer YOUR_API_KEY` 헤더가 요청에 포함되어 있는지 확인하세요.
    * 키 앞뒤에 공백이 없는지 확인하세요.
    * 환경 변수에서 키를 불러오는 경우, 실제로 값이 주입되고 있는지 확인하세요.
    * 콘솔에서 해당 키가 아직 유효한 상태인지 확인하세요.
  </Accordion>

  <Accordion title="시크릿 키를 분실했습니다">
    시크릿 키는 발급 시 한 번만 확인할 수 있으며, 이후에는 다시 조회할 수 없습니다.

    콘솔에서 기존 키를 삭제하고 새 키를 발급받으세요. 발급 즉시 복사해 환경 변수에 안전하게 보관하는 것을 권장합니다.
  </Accordion>
</AccordionGroup>

## 크레딧 / 과금 오류

<AccordionGroup>
  <Accordion title="402 Payment Required — 크레딧이 부족합니다">
    **원인:** 조직의 AU 잔액이 0 이하로 소진되어 API 호출이 차단된 상태입니다.

    **해결 방법:**

    * 콘솔 **Billing** 페이지에서 AU를 충전하세요.
    * 충전 후 API 호출을 다시 시도하면 바로 재개됩니다.
    * 반복적인 크레딧 소진을 방지하려면 자동 충전(Auto Top-up)을 설정해두세요.

    <Note>
      크레딧 소진 시 정확히 어떤 오류 메시지가 반환되는지는 (내부에서 확인 필요)
    </Note>
  </Accordion>
</AccordionGroup>

## 요청 형식 오류

<AccordionGroup>
  <Accordion title="422 Unprocessable Entity — 요청 파라미터가 잘못되었습니다">
    **원인:** 요청 본문의 파라미터 타입이나 필드명이 올바르지 않습니다.

    **확인 사항:**

    * `messages` 배열에 `role`과 `content` 필드가 모두 포함되어 있는지 확인하세요.
    * `temperature`, `max_tokens` 등 숫자 파라미터에 문자열이 들어가지 않았는지 확인하세요.
    * API 레퍼런스에서 각 파라미터의 허용 범위를 확인하세요.
  </Accordion>

  <Accordion title="모델 ID가 잘못되었거나 인식되지 않습니다">
    **원인:** `model` 파라미터에 입력한 ID가 실제 모델 ID와 다릅니다.

    **해결 방법:**

    * 콘솔에서 **코드 보기**를 클릭하면 해당 모델의 정확한 모델 ID가 포함된 코드 샘플을 확인할 수 있습니다. 이 값을 그대로 복사해 사용하세요.
  </Accordion>
</AccordionGroup>

## Rate Limit / 서비스 오류

<AccordionGroup>
  <Accordion title="429 Too Many Requests — 요청 한도를 초과했습니다">
    **원인:** 단시간에 너무 많은 요청을 보내 허용 한도를 초과했습니다.

    **해결 방법:**

    * 응답 헤더의 `Retry-After` 값을 확인하고 해당 시간(초) 이후에 재시도하세요.
    * 요청을 일정 간격으로 분산하거나 지수 백오프(exponential backoff)를 적용하세요.

    <Note>
      Air API의 모델별 RPM/TPM 한도는 (내부에서 확인 필요)
    </Note>
  </Accordion>

  <Accordion title="408 Request Timeout — 요청이 시간 초과되었습니다">
    **원인:** 모델 응답 생성에 설정된 제한 시간을 초과했습니다. 긴 `max_tokens` 값이나 복잡한 입력에서 발생할 수 있습니다.

    **해결 방법:**

    * `max_tokens` 값을 줄여 응답 길이를 제한하세요.
    * 클라이언트 측 timeout 설정이 너무 짧지 않은지 확인하세요.
    * 잠시 후 재시도하세요.
  </Accordion>

  <Accordion title="502 Bad Gateway / 503 Service Unavailable — 서비스 오류">
    **원인:** 모델 서비스가 일시적으로 응답하지 않거나 점검 중입니다. RunPod, OpenRouter 등 주요 클라우드 API에서도 공통으로 발생하는 오류입니다.

    **해결 방법:**

    * 수 초\~수 분 후 재시도하세요.
    * 동일한 오류가 지속된다면 [문의 및 피드백](/docs/ko/support/contact-and-feedback) 채널로 알려주세요.

    <Note>
      AirCloud 서비스 상태 페이지 URL은 (내부에서 확인 필요)
    </Note>
  </Accordion>

  <Accordion title="응답이 너무 느립니다">
    **원인:** 모델 부하, 입력 길이, 또는 `max_tokens` 설정에 따라 응답 시간이 길어질 수 있습니다.

    **확인 사항:**

    * `max_tokens` 값을 필요한 만큼만 설정하세요.
    * Playground에서 동일한 입력으로 응답 속도를 먼저 확인하세요.
    * 지연이 지속된다면 다른 모델(예: 더 작은 파라미터 모델)로 전환을 검토하세요.
  </Accordion>
</AccordionGroup>

## Playground 오류

<AccordionGroup>
  <Accordion title="Playground 테스트가 되지 않습니다">
    아래 항목을 순서대로 확인하세요.

    1. 브라우저를 새로고침한 뒤 다시 시도하세요.
    2. 올바른 프로젝트와 모델이 선택되어 있는지 확인하세요.
    3. 크레딧 잔액이 충분한지 확인하세요.
    4. 시크릿 브라우저 모드나 다른 브라우저에서 시도해보세요.
  </Accordion>

  <Accordion title="Embedding 모델에서 Playground가 보이지 않습니다">
    Embedding 모델은 Playground를 지원하지 않습니다. API 호출로만 사용할 수 있으며, 이는 정상적인 동작입니다.

    코드 예시는 [API 호출 방법](/docs/ko/air-api/api-usage-guide) 페이지를 참고하세요.
  </Accordion>
</AccordionGroup>

## 모델 관련

<AccordionGroup>
  <Accordion title="원하는 모델이 목록에 없습니다">
    지원 모델은 지속적으로 추가되고 있습니다. 필요한 모델이 목록에 없는 경우 [문의 및 피드백](/docs/ko/support/contact-and-feedback) 채널을 통해 요청할 수 있습니다.
  </Accordion>

  <Accordion title="403 Forbidden — 모델에 접근할 수 없습니다">
    **원인:** 현재 계정 또는 프로젝트에서 해당 모델에 대한 접근 권한이 없습니다.

    <Note>
      Air API의 모델별 접근 권한 체계는 (내부에서 확인 필요)
    </Note>
  </Accordion>
</AccordionGroup>

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

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