오류 코드 처리

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 실패 응답은 다음과 같은 오류 본문을 사용합니다:

{
	"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와 비교하세요. 다음과 같은 최소 요청을 사용하세요:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

your-model-id는 CometAPI Models page의 현재 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가 누락된 요청이 있습니다:

{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}

500 응답에 error.code: invalid_request가 있으면 요청 문제로 처리하세요:

요청 본문을 수정합니다.
payload를 endpoint schema와 비교합니다.
payload를 수정한 후에만 재시도합니다.

500 응답이 잘못된 요청을 가리키지 않는다면, request id를 보관하고 백오프를 사용하세요.

`401 Invalid Token`

토큰 실패는 보통 다음과 같이 나타납니다:

{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}

확인할 사항:

헤더는 정확히 Authorization: Bearer $COMETAPI_KEY 이어야 합니다.
앱이 .env, shell 기록, 또는 배포된 secret store에서 오래된 키를 불러오고 있지 않은지 확인하세요.
하나의 키는 실패하고 다른 키는 동일한 요청에서 작동한다면, 이를 endpoint 문제가 아니라 토큰 문제로 판단하세요.

`403 Forbidden`

403은 대부분 다음 상황 중 하나입니다:

요청이 WAF 필터링과 같은 플랫폼 측 규칙에 의해 차단됨
token 또는 route가 요청한 model 또는 요청 형식을 사용할 수 없음
선택한 model이 전달한 고급 파라미터 중 하나를 거부함

먼저 할 일:

정상 작동이 확인된 model에 대해 매우 단순한 텍스트 요청으로 다시 시도하세요.
고급 필드와 provider별 파라미터를 제거한 뒤, 점진적으로 다시 추가하세요.
응답에 request id가 포함되어 있다면 support에 문의하기 전에 이를 보관하세요.

메시지에 group 또는 channel 같은 내부 용어가 언급되더라도, 이를 클라이언트 측에서 가장 먼저 진단해야 할 대상으로 보지 마세요. 실질적인 해결 방법은 여전히 먼저 token, model, 그리고 요청 형식을 검증하는 것입니다.

Wrong base URL or wrong path

Comet에서는 path 실수가 다음과 같이 나타날 수 있습니다:

리디렉션
클라이언트가 리디렉션을 따르는 경우 JSON이 아닌 HTML 응답
SDK 내부의 파싱 오류
요청이 API 계층에 정상적으로 도달하지 못함

다음 base URL을 정확히 사용하세요:

https://api.cometapi.com/v1

권장 확인 사항:

base URL에 /v1가 포함되어 있는지 확인하세요.
endpoint path가 문서와 정확히 일치하는지 확인하세요.
path 문제를 디버깅하는 동안 자동 리디렉션 추적을 비활성화하세요.

`413 Request Entity Too Large`

413이 표시되면, 먼저 요청 크기 문제로 간주하세요. 일반적인 원인은 다음과 같습니다:

큰 base64 payload
인라인으로 포함된 지나치게 큰 이미지 또는 오디오
매우 큰 multipart 또는 JSON 본문

해야 할 일:

첨부된 콘텐츠를 줄이거나 압축하세요.
큰 작업을 더 작은 요청으로 나누세요.
일반 텍스트 길이만이 유일한 원인이라고 가정하지 마세요.

`429 Too Many Requests`

429는 재시도 가능한 오류로 처리하세요:

jitter를 포함한 지수 백오프를 사용하세요.
burst 동시성을 줄이세요.
어떤 route와 model이 먼저 포화되는지 확인할 수 있도록 요청 로깅을 계속 활성화해 두세요.

재사용 가능한 재시도 패턴은 채팅 완성의 backoff 예제를 참고하세요.

`503`, `504`, and `524`

이 상태 코드는 서버 측 또는 타임아웃 계열 실패입니다. 실용적인 가이드:

503: route 또는 provider 서비스가 일시적으로 사용 불가
504 및 524: 플랫폼, edge, 또는 provider 서비스 사이에서 발생한 타임아웃 계열 실패

해야 할 일:

백오프를 적용해 재시도하세요.
request id, endpoint, model, 그리고 timestamp를 보관하세요.
동일한 실패가 여러 번의 재시도에서도 반복된다면, 해당 맥락 정보와 함께 support에 문의하세요.

지원팀에 문의하기 전에

먼저 다음 세부 정보를 수집하세요:

HTTP 메서드
엔드포인트 경로
Model ID
민감 정보를 제거한 요청 본문 JSON (대부분의 API 호출에서 가장 유용한 단일 항목입니다)
실패한 요청에서 사용했다면 쿼리 파라미터
클라이언트가 캡처했다면 정확한 응답 본문
전체 HTTP 상태 코드
정확한 error.message
모든 request id
대략적인 타임스탬프
동일한 요청이 다른 model 또는 다른 token으로는 작동하는지 여부

실패한 라우트가 일반 JSON 본문 대신 파일 업로드(이미지 편집, 오디오 업로드, 비디오 생성 등)를 받는 경우, 이에 해당하는 제출 페이로드를 보내세요:

파일과 함께 전송한 필드 이름과 텍스트 값
파일 이름, 파일 유형, 대략적인 파일 크기
파일을 직접 업로드했는지, URL로 참조했는지, 또는 base64로 포함했는지 여부

버그를 재현하는 가장 효과적인 방법은 정확한 민감 정보 제거 요청 페이로드입니다. 대부분의 API 호출에서는 원시 요청 본문 JSON을 의미합니다. 파일 업로드 라우트에서는 필드 목록과 파일 메타데이터를 의미합니다.

이렇게 하면 지원 처리 시간이 크게 단축됩니다.

여기서 시작하기

모델 API 빠른 시작

핵심 API 가이드

라이브러리

오류

요금 및 청구

지원

빠른 분류

오류 envelope

`400 Bad Request`

`500 Internal Server Error`

`401 Invalid Token`

`403 Forbidden`

Wrong base URL or wrong path

`413 Request Entity Too Large`

`429 Too Many Requests`

`503`, `504`, and `524`

지원팀에 문의하기 전에

​빠른 분류

​오류 envelope

​400 Bad Request

​500 Internal Server Error

​401 Invalid Token

​403 Forbidden

​Wrong base URL or wrong path

​413 Request Entity Too Large

​429 Too Many Requests

​503, 504, and 524

​지원팀에 문의하기 전에

빠른 분류

오류 envelope

`400 Bad Request`

`500 Internal Server Error`

`401 Invalid Token`

`403 Forbidden`

Wrong base URL or wrong path

`413 Request Entity Too Large`

`429 Too Many Requests`

`503`, `504`, and `524`

지원팀에 문의하기 전에