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

# 오류 코드

> 요청 실패 범위를 빠르게 좁힐 수 있는 API 가이드 내의 오류 코드 가이드입니다.

오류 응답은 주로 HTTP 상태, `error.type`, `error.code`, `error.message` 및 `X-Request-Id`로 설명됩니다.

## 오류 응답 형태

* HTTP 상태: 요청의 최종 실패 클래스입니다.
* `X-Request-Id`: 추적 ID를 요청합니다. 클라이언트가 메시지를 보내지 않으면 게이트웨이는 이를 생성하고 실패 시 반환을 시도합니다.
* `error.message`: 호출자에 대해 사람이 읽을 수 있는 오류 설명입니다.
* `error.type`: 오류 유형. 안정적인 MaaS 게이트웨이 오류는 현재 `invalid_request_error`를 사용합니다. 업스트림 플랫폼 오류는 다른 값을 사용할 수 있습니다.
* `error.code`: 오류 코드. MaaS 게이트웨이 오류는 안정적인 코드를 사용합니다. 업스트림 플랫폼 오류에는 이 필드가 생략될 수 있습니다.

```json Example response theme={null}
{
  "error": {
    "message": "upstream provider credentials unavailable",
    "type": "invalid_request_error",
    "code": "missing_upstream_key"
  }
}
```

## 오류 원인

### MaaS 게이트웨이

| `error.code`                | HTTP 상태 | `error.type`            | `error.message`                                               | Meaning                                                    |
| --------------------------- | ------- | ----------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
| `missing_upstream_key`      | `502`   | `invalid_request_error` | `upstream provider credentials unavailable`                   | 현재 업스트림 서비스를 사용할 수 없습니다. 플랫폼 관리자에게 공급자 자격 증명을 확인하도록 요청하세요. |
| `invalid_upstream_key_info` | `502`   | `invalid_request_error` | `invalid key info response`                                   | 업스트림 서비스 구성이 잘못되어 요청을 완료할 수 없습니다.                          |
| `masked_upstream_key`       | `502`   | `invalid_request_error` | `upstream provider credentials are masked and cannot be used` | 업스트림 서비스 인증 정보를 사용할 수 없으므로 요청을 완료할 수 없습니다.                 |

### 업스트림 플랫폼 오류

일부 요청은 업스트림 플랫폼에서 직접 오류를 반환할 수 있습니다. 이 경우 실제 HTTP 상태와 반환된 `error` 개체를 활용하세요.

* HTTP 상태: 반환된 상태를 있는 그대로 사용합니다.
* 응답 본문: 일반적으로 플랫폼의 `error.type`, `error.code` 및 `error.message`를 포함합니다.
* `X-Request-Id`: 지원 및 로그 조회를 위해 보관하세요.
* 문서 경계: 모든 업스트림 `type` 또는 `code` 값을 안정적인 MaaS 게이트웨이 오류 코드로 처리하지 마십시오.

```json Platform passthrough example theme={null}
{
  "error": {
    "message": "daily credits exhausted",
    "type": "insufficient_quota"
  }
}
```

이 `402` 예는 크레딧 또는 잔액이 소진되었음을 의미합니다. 이는 업스트림 플랫폼에서 제공되며 안정적인 MaaS 게이트웨이 오류 코드 세트의 일부가 아닙니다.

## 권장되는 디버깅 순서

1. 먼저 HTTP 상태를 확인하여 실패가 안정적인 MaaS 게이트웨이 오류인지 업스트림 플랫폼 오류인지 확인하세요.
2. 지원 및 로그 조회를 위해 `X-Request-Id`를 유지하세요.
3. `error.code`가 `missing_upstream_key`, `invalid_upstream_key_info` 또는 `masked_upstream_key`인 경우 플랫폼 관리자에게 문의하여 서비스 구성 문제를 해결하세요.
4. 응답이 업스트림 플랫폼 오류인 경우 `error.type`, `error.code` 및 `error.message`를 사용하여 할당량, 인증 또는 플랫폼 정책 문제를 진단합니다.