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

# 모델 API 오류를 어떻게 해결할 수 있습니까?

> 매개변수, 인증, 429, 5xx, 시간 초과, 리소스 및 그룹 오류를 진단합니다.

## 간단한 답변

HTTP 상태 코드만으로 요청을 진단해서는 안 됩니다. 먼저 전체 오류, 모델 이름, Base URL, token 그룹, 요청 ID를 저장한 다음 문제가 **요청 구성 오류**인지 **일시적인 업스트림 장애**인지 판단해야 합니다.

* `400`, `401`, `403`, 지원되지 않는 매개변수, 안전성 차단 및 그룹 불일치는 일반적으로 요청 또는 구성 변경이 필요합니다. 동일한 요청을 반복해도 해결되지 않습니다.
* `429`, `503`, 일부 `504` 응답 및 `Upstream model timed out`은 업스트림 부하, 리소스 가용성 또는 장시간 실행되는 요청으로 인해 발생할 수 있습니다. 로그를 확인한 후 제한적인 지수 백오프 재시도를 사용합니다.
* 하나의 모델 또는 그룹만 실패하는 경우 권한이 부여된 대체 그룹을 테스트합니다. 여러 모델이 동시에 실패하는 경우 먼저 API 키, Base URL 및 네트워크 경로를 확인합니다.

## 전체 오류 저장

스크린샷에는 가장 유용한 필드가 누락되는 경우가 많습니다. 문제를 해결하기 전에 다음 정보를 보관합니다.

| 정보          | 예시                            | 중요한 이유                        |
| ----------- | ----------------------------- | ----------------------------- |
| HTTP 상태     | `400`, `401`, `429`, `503`    | 오류 유형을 식별합니다                  |
| 오류 메시지 및 코드 | `Unsupported parameter: stop` | 결정적인 요청 오류를 식별합니다             |
| 모델 및 그룹     | `gpt-5.6-luna`, `Default`     | 영향을 받는 경로를 정의합니다              |
| 기본 URL      | `https://api.apiyi.com/v1`    | 엔드포인트 및 노드 설정을 확인하는 데 도움이 됩니다 |
| 요청 ID       | 응답에 반환된 ID                    | 지원팀이 요청을 찾는 데 도움이 됩니다         |
| 타임스탬프       | 시간대를 포함합니다                    | 업스트림 및 로그 기록을 대조하는 데 도움이 됩니다  |
| 로그 기록       | 과금 기록이 존재하는지 여부               | 생성이 시작되었는지 보여줍니다              |

<Warning>
  티켓, 스크린샷 또는 코드 샘플에 전체 API 키를 절대 노출하지 마십시오. 오류 메시지, 요청 ID 및 마스킹된 구성만 남겨 두십시오.
</Warning>

## 오류 유형별 문제 해결

| 오류                                            | 일반적인 원인                                                   | 첫 번째 조치                                                         |
| --------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------- |
| `400` 또는 `Unsupported parameter`              | 일부 경량 모델에서 `stop`와 같은 요청 필드를 지원하지 않음                      | 지원되지 않는 필드를 제거하고 최소 요청을 테스트합니다. 변경하지 않은 요청을 재시도하지 마십시오          |
| `401 Invalid token` 또는 `403`                  | API 키, 기본 URL, token 상태 또는 그룹 권한 불일치                      | API 키와 기본 URL을 확인한 다음 token 그룹 및 모델 권한을 확인합니다                   |
| `429`                                         | 과도한 동시 실행 수 또는 업스트림 포화입니다. 메시지에 요청 호환성 문제가 숨겨져 있을 수도 있습니다 | 전체 오류를 확인하고 동시 실행 수를 줄인 후 지수 백오프를 사용합니다. 문제가 지속되면 쿼터와 그룹을 확인합니다 |
| `503` 또는 `Service unavailable`                | 일시적인 사용 불가, 업스트림 리소스 부족 또는 그룹에 사용 가능한 채널이 없음              | 잠시 기다린 후 제한된 횟수로 재시도합니다. 필요한 경우 권한이 있는 대체 그룹을 사용합니다             |
| `504` 또는 `Upstream model timed out`           | 업스트림 처리 지연, 업스트림 불안정 또는 요청 경로 어딘가에서 발생한 타임아웃              | 로그와 클라이언트 타임아웃을 확인합니다. 장시간 요청에 CDN 노드를 사용하고 있지 않은지 확인합니다        |
| `RESOURCE_EXHAUSTED`                          | 업스트림 컴퓨팅 리소스 또는 동시 실행 수 리소스의 일시적인 부족                      | 동시 실행 수를 줄이고 복구를 기다리거나, 사용 가능한 다른 그룹/모델을 사용합니다                  |
| `rejected by the safety system` 또는 `NO_IMAGE` | 요청이 업스트림 콘텐츠 안전 정책을 트리거함                                  | prompt 또는 입력을 변경합니다. 동일한 요청을 변경 없이 제출하지 마십시오                    |
| 모델을 사용할 수 없거나 그룹이 일치하지 않음                     | token에 필요한 그룹이 포함되지 않았거나, 모델 허용 목록이 모델을 차단하거나, 모델 이름이 잘못됨 | token의 기본 그룹, 대체 그룹 및 허용된 모델을 확인합니다                             |

<Info>
  동일한 상태 코드에도 원인이 다를 수 있습니다. 예를 들어 `429`는 업스트림 포화를 의미할 수 있지만, 전체 오류 메시지에만 세부 정보가 표시되는 요청 호환성 문제일 수도 있습니다. 응답 본문과 호출 로그를 최종 근거로 사용합니다.
</Info>

## 표준 문제 해결 단계

<Steps>
  <Step title="1단계: 최소 요청으로 재현합니다">
    선택적 파라미터, tool 정의, 복잡한 이미지 입력 및 긴 prompt를 일시적으로 제거합니다. 모델, 필수 메시지 및 인증 정보만 유지합니다. 이를 통해 요청 오류를 경로 또는 모델 오류와 구분할 수 있습니다.
  </Step>

  <Step title="2단계: 엔드포인트, token 및 그룹을 확인합니다">
    API 키가 `api.apiyi.com` Base URL과 함께 사용되는지 확인합니다. 콘솔에서 token의 기본 그룹, 대체 그룹 및 허용된 모델을 확인합니다. 일부 모델에는 전용 그룹이 필요합니다.
  </Step>

  <Step title="3단계: 재시도가 적절한지 판단합니다">
    `429`, `503` 및 확인된 일시적 업스트림 장애에는 백오프 재시도를 사용합니다. 파라미터 오류, 안전 차단, 잘못된 모델 이름 및 그룹 불일치의 경우에는 변경 없이 재시도하는 대신 요청 또는 구성을 변경합니다.
  </Step>

  <Step title="4단계: 타임아웃 및 네트워크 경로를 확인합니다">
    이미지 생성, 추론 모델 및 긴 텍스트 요청에는 더 긴 타임아웃이 필요합니다. 약 100초 제한이 있는 `api-cf.apiyi.com` CDN 노드 대신 긴 요청에는 `api.apiyi.com` 또는 `vip.apiyi.com`을 사용합니다.
  </Step>

  <Step title="5단계: 다시 전송하기 전에 호출 로그를 확인합니다">
    요청이 과금 기록을 생성했는지 확인합니다. 클라이언트 타임아웃 또는 연결 해제가 항상 서버 측 처리가 중단되었음을 의미하지는 않으므로, 상태를 확인하기 전에 무작정 요청을 다시 전송하지 마십시오.
  </Step>
</Steps>

## 최소 테스트 요청

다음 요청을 사용하여 엔드포인트, token 및 기본 모델 호출을 확인합니다. `YOUR_MODEL`을(를) 사용 중인 token으로 이용 가능한 모델로 교체하고, 최소 호출이 작동할 때까지 선택적 필드를 추가하지 마십시오.

```bash theme={null}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      {"role": "user", "content": "Reply with: test successful"}
    ]
  }'
```

## 반복 오류 방지

* 최소 요청으로 시작한 다음 `stop`, tools, 추론 제어, 이미지 및 기타 선택적 필드를 한 번에 하나씩 추가합니다.
* 모든 모델이 동일한 필드를 지원한다고 가정하지 말고, 모델별 매개변수 호환성 표를 관리합니다.
* `429`이 발생한 직후 여러 동시 요청을 다시 전송하지 말고, 지수 백오프를 사용하며 모델별 동시 실행 수를 제어합니다.
* 이미지 및 추론 요청에는 충분한 타임아웃을 설정합니다. SDK 재시도와 자체 비즈니스 계층 재시도를 중복해서 사용하지 않습니다.
* 실제 프로덕션 매개변수로 테스트한 대체 그룹을 구성합니다.

## 자주 묻는 질문

<AccordionGroup>
  <Accordion title="429는 항상 동시 실행 수가 너무 높다는 의미입니까?">
    아닙니다. `429`은 동시 실행 수 또는 업스트림 포화로 인해 발생할 수 있지만, 오류 메시지에 매개변수 호환성 문제가 숨겨져 있을 수도 있습니다. 동시 실행 수를 낮추거나 요청을 변경할지 결정하기 전에 전체 `error.message`을 확인하십시오.
  </Accordion>

  <Accordion title="401 이후에는 항상 새 token을 생성해야 합니까?">
    아닙니다. 먼저 요청에서 APIYI의 기본 URL을 사용하는지 확인한 다음, token이 만료되었는지와 올바른 그룹이 선택되었는지 확인하십시오. 하나의 모델에서만 `Invalid token`이 5xx 또는 시간 초과 오류와 함께 반환된다면 업스트림 경로가 원인일 수도 있습니다.
  </Accordion>

  <Accordion title="시간 초과 후 즉시 재시도해도 됩니까?">
    먼저 호출 로그를 확인하십시오. 클라이언트 시간 초과는 클라이언트가 대기를 중단했다는 의미일 뿐이며, 서버 측 처리는 계속 진행 중일 수 있습니다. 요청에 과금 기록이 있다면 즉시 재시도할 경우 호출이 중복으로 생성될 수 있습니다.
  </Accordion>

  <Accordion title="실패한 요청에도 과금됩니까?">
    오류 페이지만으로 판단하지 마십시오. 모델 생성에 도달하지 않은 매개변수 검증, 인증 및 안전 차단은 일반적으로 최종 과금을 생성하지 않지만, 클라이언트 연결 끊김 또는 이미 업스트림 처리가 시작된 요청에는 과금될 수 있습니다. 호출 로그를 기준 정보로 사용하십시오.
  </Accordion>
</AccordionGroup>

## 아직 해결되지 않았습니까? 지원팀에 문의하십시오

위 단계를 수행한 후에도 문제가 지속되면 WeCom 또는 이메일을 통해 APIYI 지원팀에 문의하십시오. 문제 해결을 신속하게 진행할 수 있도록 다음 정보를 포함하십시오.

* 모델 이름, token 그룹 및 베이스 URL
* 전체 오류 메시지, HTTP 상태 및 요청 ID
* `UTC+8` 시간대를 포함한 발생 시간
* 축소한 요청 예시 또는 민감 정보가 삭제된 요청 본문
* 호출 로그에 과금 기록이 포함되어 있는지 여부

<Warning>
  완전한 API 키를 보내지 마십시오. 접두사와 마지막 몇 개 문자만 표시하고 나머지는 삭제하십시오.
</Warning>

<CardGroup cols={2}>
  <Card title="WeCom 지원" icon="message-circle" href="https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec">
    <img src="https://mintcdn.com/apiyillc/fpi567ydpk7adDt0/images/wecom-qrcode.png?fit=max&auto=format&n=fpi567ydpk7adDt0&q=85&s=7286b96e94110e3a48798b649df1b45b" alt="WeCom 지원 QR 코드" style={{maxWidth: "180px"}} width="400" height="400" data-path="images/wecom-qrcode.png" />

    QR 코드를 스캔하거나 이 카드를 클릭하여 지원팀에 직접 문의하십시오.

    모델 오류, 시간 초과, 그룹 및 과금 문제
  </Card>

  <Card title="이메일 지원" icon="mail">
    **지원**: [support@apiyi.com](mailto:support@apiyi.com)

    제목에 “모델 오류”와 모델 이름을 포함하는 것이 좋습니다.
  </Card>
</CardGroup>

## 관련 문서

<CardGroup cols={2}>
  <Card title="API 키가 유효하지 않은 이유는 무엇입니까?" icon="key" href="/ko/faq/invalid-api-key">
    기본 URL, API 키 및 인증 설정을 확인합니다
  </Card>

  <Card title="그룹이란 무엇입니까?" icon="layers" href="/ko/faq/groups-explained">
    token 그룹, 업스트림 라우트 및 대체 그룹에 대해 알아봅니다
  </Card>

  <Card title="요청 시간 초과를 방지하려면 어떻게 해야 합니까?" icon="timer" href="/ko/faq/timeout-configuration">
    시간 초과, 노드 및 장시간 요청 문제 해결을 구성합니다
  </Card>

  <Card title="동시 실행 수는 어느 정도까지 사용할 수 있습니까?" icon="gauge" href="/ko/faq/api-concurrency">
    모델 동시 실행 수 제한 및 429 관련 지침을 검토합니다
  </Card>

  <Card title="사이트 또는 API에서 502를 반환하면 어떻게 해야 합니까?" icon="server-crash" href="/ko/faq/website-502-error">
    5xx 오류, 재시도 및 과금 확인 방법을 알아봅니다
  </Card>

  <Card title="로그에서 과금 금액을 어떻게 확인합니까?" icon="file-text" href="/ko/faq/log-billing-explained">
    호출 로그를 사용하여 요청에 과금되었는지 확인합니다
  </Card>
</CardGroup>