> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 오류 코드 처리
> 이 가이드를 사용해 CometAPI 오류 응답을 분류하고, 일반적인 요청 실패에 대해 재시도 또는 수정 단계를 적용하세요.
CometAPI 오류 처리는 **요청 형식 문제**, **인증 문제**, **경로 실수**, **재시도 가능한 플랫폼 장애**를 구분하면 가장 쉽습니다. HTTP status, `error.code`, `error.message`를 함께 사용해 요청을 수정해야 하는지 아니면 재시도해야 하는지 판단하세요.
## 빠른 분류
| Status | 일반적인 의미 | 재시도? | 첫 번째 조치 |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------- |
| `400` | 요청이 정상적으로 처리되기 전에 요청 유효성 검사가 실패했습니다. | 아니요 | `model`, `messages`, JSON 형태, 필드 타입을 검증하세요. |
| `401` | API 키가 누락되었거나, 형식이 잘못되었거나, 유효하지 않습니다. | 아니요 | `Authorization: Bearer $COMETAPI_KEY`를 확인하세요. |
| `403` | 접근이 차단되었거나 현재 요청이 허용되지 않았습니다. | 보통 아니요 | 정상 동작이 확인된 요청으로 다시 시도하고 먼저 모델별 필드를 제거하세요. |
| Path mistake | 잘못된 base URL 또는 잘못된 endpoint 경로입니다. Comet에서는 이것이 깔끔한 JSON `404`가 아니라 `301` 리디렉션이나 HTML로 나타날 수 있습니다. | 아니요 | `https://api.cometapi.com/v1`를 정확히 사용하고, 디버깅 중에는 자동 리디렉션 따라가기를 비활성화하세요. |
| `429` | 속도 제한 또는 일시적인 포화 상태입니다. | 예 | 지터를 포함한 지수 백오프를 사용하세요. |
| `500` with `error.code: invalid_request` | 잘못된 요청이 서버 status 응답을 통해 드러난 경우입니다. | 아니요 | 재시도하기 전에 요청 본문을 수정하세요. |
| `500`, `503`, `504`, `524` | 플랫폼, provider 또는 타임아웃 계열 장애입니다. | 예 | 백오프를 적용해 재시도하고 request id를 유지하세요. |
## 오류 envelope
많은 CometAPI 실패 응답은 다음과 같은 오류 본문을 사용합니다:
```json theme={null}
{
"error": {
"message": "...",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
일부 응답은 `code`를 비워 둡니다. status가 `500`인 경우, `error.code`와 `error.message`를 판단 기준으로 삼으세요.
## `400 Bad Request`
`400`은 보통 요청이 정상적으로 처리되기 전에 요청 본문이 유효성 검사를 통과하지 못했음을 의미합니다.
일반적인 원인:
* `model` 같은 필수 필드 누락
* 잘못된 JSON 형태
* 잘못된 타입의 필드 전송
* 선택한 endpoint가 허용하지 않는 provider 전용 파라미터 재사용
최소한의 정상 동작 요청부터 시작한 뒤, 선택적 필드를 하나씩 다시 추가하세요. payload를 API reference의 endpoint schema와 비교하세요.
다음과 같은 최소 요청을 사용하세요:
```json theme={null}
{
"model": "your-model-id",
"messages": [
{
"role": "user",
"content": "Hello"
}
]
}
```
`your-model-id`는 [CometAPI Models page](/ko/overview/models)의 현재 model ID로 바꾸세요.
형식이 잘못된 모든 chat 요청이 `400`을 반환한다고 가정하지 마세요. `messages` 같은 필수 chat 필드 누락은 `500`과 `error.code: invalid_request`로도 나타날 수 있습니다.
## `500 Internal Server Error`
대부분의 `500` 응답은 플랫폼 또는 provider 장애를 의미합니다. Chat Completions의 경우, 일부 형식이 잘못된 요청도 `500`으로 나타나면서 `error.code: invalid_request`를 함께 포함할 수 있습니다.
그 예로 `messages`가 누락된 요청이 있습니다:
```json theme={null}
{
"error": {
"message": "field messages is required (request id: ...)",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
`500` 응답에 `error.code: invalid_request`가 있으면 요청 문제로 처리하세요:
1. 요청 본문을 수정합니다.
2. payload를 endpoint schema와 비교합니다.
3. payload를 수정한 후에만 재시도합니다.
`500` 응답이 잘못된 요청을 가리키지 않는다면, `request id`를 보관하고 백오프를 사용하세요.
## `401 Invalid Token`
토큰 실패는 보통 다음과 같이 나타납니다:
```json theme={null}
{
"error": {
"code": "",
"message": "invalid token (request id: ...)",
"type": "comet_api_error"
}
}
```
확인할 사항:
1. 헤더는 정확히 `Authorization: Bearer $COMETAPI_KEY` 이어야 합니다.
2. 앱이 `.env`, shell 기록, 또는 배포된 secret store에서 오래된 키를 불러오고 있지 않은지 확인하세요.
3. 하나의 키는 실패하고 다른 키는 동일한 요청에서 작동한다면, 이를 endpoint 문제가 아니라 토큰 문제로 판단하세요.
## `403 Forbidden`
`403`은 대부분 다음 상황 중 하나입니다:
* 요청이 WAF 필터링과 같은 플랫폼 측 규칙에 의해 차단됨
* token 또는 route가 요청한 model 또는 요청 형식을 사용할 수 없음
* 선택한 model이 전달한 고급 파라미터 중 하나를 거부함
먼저 할 일:
1. 정상 작동이 확인된 model에 대해 매우 단순한 텍스트 요청으로 다시 시도하세요.
2. 고급 필드와 provider별 파라미터를 제거한 뒤, 점진적으로 다시 추가하세요.
3. 응답에 request id가 포함되어 있다면 support에 문의하기 전에 이를 보관하세요.
메시지에 `group` 또는 `channel` 같은 내부 용어가 언급되더라도, 이를 클라이언트 측에서 가장 먼저 진단해야 할 대상으로 보지 마세요. 실질적인 해결 방법은 여전히 먼저 token, model, 그리고 요청 형식을 검증하는 것입니다.
## Wrong base URL or wrong path
Comet에서는 path 실수가 다음과 같이 나타날 수 있습니다:
* 리디렉션
* 클라이언트가 리디렉션을 따르는 경우 JSON이 아닌 HTML 응답
* SDK 내부의 파싱 오류
* 요청이 API 계층에 정상적으로 도달하지 못함
다음 base URL을 정확히 사용하세요:
```text theme={null}
https://api.cometapi.com/v1
```
권장 확인 사항:
1. base URL에 `/v1`가 포함되어 있는지 확인하세요.
2. endpoint path가 문서와 정확히 일치하는지 확인하세요.
3. path 문제를 디버깅하는 동안 자동 리디렉션 추적을 비활성화하세요.
## `413 Request Entity Too Large`
`413`이 표시되면, 먼저 **요청 크기** 문제로 간주하세요. 일반적인 원인은 다음과 같습니다:
* 큰 base64 payload
* 인라인으로 포함된 지나치게 큰 이미지 또는 오디오
* 매우 큰 multipart 또는 JSON 본문
해야 할 일:
1. 첨부된 콘텐츠를 줄이거나 압축하세요.
2. 큰 작업을 더 작은 요청으로 나누세요.
3. 일반 텍스트 길이만이 유일한 원인이라고 가정하지 마세요.
## `429 Too Many Requests`
`429`는 재시도 가능한 오류로 처리하세요:
1. jitter를 포함한 지수 백오프를 사용하세요.
2. burst 동시성을 줄이세요.
3. 어떤 route와 model이 먼저 포화되는지 확인할 수 있도록 요청 로깅을 계속 활성화해 두세요.
재사용 가능한 재시도 패턴은 [채팅 완성](/api/text/chat)의 backoff 예제를 참고하세요.
## `503`, `504`, and `524`
이 상태 코드는 **서버 측 또는 타임아웃 계열 실패**입니다.
실용적인 가이드:
* `503`: route 또는 provider 서비스가 일시적으로 사용 불가
* `504` 및 `524`: 플랫폼, edge, 또는 provider 서비스 사이에서 발생한 타임아웃 계열 실패
해야 할 일:
1. 백오프를 적용해 재시도하세요.
2. `request id`, endpoint, model, 그리고 timestamp를 보관하세요.
3. 동일한 실패가 여러 번의 재시도에서도 반복된다면, 해당 맥락 정보와 함께 support에 문의하세요.
## 지원팀에 문의하기 전에
먼저 다음 세부 정보를 수집하세요:
* HTTP 메서드
* 엔드포인트 경로
* Model ID
* **민감 정보를 제거한 요청 본문 JSON** (대부분의 API 호출에서 가장 유용한 단일 항목입니다)
* 실패한 요청에서 사용했다면 쿼리 파라미터
* 클라이언트가 캡처했다면 정확한 응답 본문
* 전체 HTTP 상태 코드
* 정확한 `error.message`
* 모든 `request id`
* 대략적인 타임스탬프
* 동일한 요청이 다른 model 또는 다른 token으로는 작동하는지 여부
실패한 라우트가 일반 JSON 본문 대신 **파일 업로드**(이미지 편집, 오디오 업로드, 비디오 생성 등)를 받는 경우, 이에 해당하는 제출 페이로드를 보내세요:
* 파일과 함께 전송한 필드 이름과 텍스트 값
* 파일 이름, 파일 유형, 대략적인 파일 크기
* 파일을 직접 업로드했는지, URL로 참조했는지, 또는 base64로 포함했는지 여부
버그를 재현하는 가장 효과적인 방법은 정확한 민감 정보 제거 요청 페이로드입니다. 대부분의 API 호출에서는 **원시 요청 본문 JSON**을 의미합니다. 파일 업로드 라우트에서는 필드 목록과 파일 메타데이터를 의미합니다.
이렇게 하면 지원 처리 시간이 크게 단축됩니다.