오류 코드 및 처리

400, 401, 경로 오류에 대한 검증된 가이드와 함께 403, 429, 타임아웃 계열 실패에 대한 실용적인 처리 방법으로 CometAPI 요청 실패를 해결하세요.

CometAPI 오류 처리는 요청 문제, 인증 문제, 재시도 가능한 플랫폼 문제를 구분할 때 가장 수월합니다. 이 페이지는 CometAPI의 공식 오류 가이드이며, 먼저 클라이언트 측에서 확인할 수 있는 사항에 중점을 둡니다.

이 가이드는 현재 CometAPI API에 대한 실시간 점검을 기반으로 합니다. 400, 401, 그리고 경로/base URL 실패는 직접 검증했습니다. 413, 429, 500, 503, 504, 524는 제한된 테스트에서 재현하지 못했기 때문에, 해당 상태 코드에 대한 안내는 의도적으로 보수적으로 작성되었습니다.

​

빠른 분류

Status	일반적인 의미	재시도?	첫 번째 조치
400	요청이 정상적으로 라우팅되기 전에 요청 유효성 검사가 실패했습니다.	아니요	model, messages, JSON 구조, 필드 타입을 검증하세요.
401	API 키가 없거나, 형식이 잘못되었거나, 유효하지 않습니다.	아니요	Authorization: Bearer <COMETAPI_KEY>를 확인하세요.
403	접근이 차단되었거나 현재 요청이 허용되지 않았습니다.	보통 아니요	정상 동작이 확인된 요청으로 다시 시도하고 먼저 모델별 필드를 제거하세요.
Path mistake	base URL 또는 엔드포인트 경로가 잘못되었습니다. Comet에서는 깔끔한 JSON 404가 아니라 301 리디렉션이나 HTML로 나타날 수 있습니다.	아니요	정확히 https://api.cometapi.com/v1를 사용하고 디버깅 중에는 자동 리디렉션 따라가기를 비활성화하세요.
429	속도 제한 또는 일시적인 포화 상태입니다.	예	지터가 포함된 exponential backoff를 사용하세요.
500, 503, 504, 524	플랫폼 또는 타임아웃 계열 실패입니다.	예	backoff로 재시도하고 request id를 보관하세요.

​

오류 Envelope

현재 CometAPI가 반환하는 JSON 오류 envelope는 다음과 같습니다:

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

실제 오류 메시지에는 error.message 안에 request id가 포함되는 경우도 많습니다. 지원이 필요할 때를 대비해 이 값을 저장해 두세요.

​

400 Bad Request

model이 생략되었을 때 실제 API에서 관찰한 내용은 다음과 같습니다:

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

실제로 400은 보통 플랫폼이 요청을 모델 제공자에게 라우팅하기 전에 요청 본문이 유효성 검사에 실패했음을 의미합니다.

일반적인 원인:

• model 또는 messages 같은 필수 필드 누락
• 잘못된 JSON 구조
• 잘못된 타입의 필드 전송
• 선택한 엔드포인트가 허용하지 않는 제공자별 파라미터를 재사용함

대응 방법:

1. 최소한의 정상 동작이 확인된 요청에서 시작하세요.
2. 선택 필드를 하나씩 다시 추가하세요.
3. API 레퍼런스의 엔드포인트 스키마와 요청 본문을 비교하세요.

최소 정상 요청 예시:

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

your-model-id는 CometAPI Models page에서 현재 사용 가능한 모델 ID로 바꾸세요.

​

401 Invalid Token

유효하지 않은 키로 실제 API에서 관찰한 내용은 다음과 같습니다:

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

확인할 사항:

1. 헤더는 반드시 정확히 Authorization: Bearer <COMETAPI_KEY> 형식이어야 합니다.
2. 앱이 .env, 셸 히스토리, 또는 배포된 secret store에서 오래된 키를 불러오고 있지 않은지 확인하세요.
3. 같은 요청에서 한 키는 실패하고 다른 키는 동작한다면, 이를 엔드포인트 문제가 아니라 토큰 문제로 판단하세요.

​

403 Forbidden

제한된 테스트에서는 안정적으로 403을 재현하지 못했으므로, 오래된 단일 메시지 템플릿을 전체 상황으로 간주하지 마세요.

현재 Comet 문서에서 403은 보통 다음 상황 중 하나로 설명됩니다:

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

먼저 해야 할 일:

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

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

​

잘못된 Base URL 또는 잘못된 경로

이 영역은 이전 페이지가 가장 부정확했던 부분입니다.

현재 Comet 엔드포인트를 대상으로 한 실제 점검에서는:

• https://api.cometapi.com/chat/completions에 POST 요청을 보내면 https://www.cometapi.com/chat/completions로 301 리디렉션이 반환되었습니다
• https://api.cometapi.com/v1/not-a-real-endpoint 같은 가짜 API route에 POST 요청을 보내도 https://www.cometapi.com/v1/not-a-real-endpoint로 301 리디렉션이 반환되었습니다

즉, 경로 실수는 다음과 같은 형태로 나타날 수 있습니다:

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

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

https://api.cometapi.com/v1

권장 점검 사항:

1. base URL에 /v1이 포함되어 있는지 확인합니다.
2. 엔드포인트 경로가 문서와 정확히 일치하는지 확인합니다.
3. 경로 문제를 디버깅하는 동안에는 자동 리디렉션 추적을 비활성화합니다.

​

413 Request Entity Too Large

제한된 테스트에서는 8 MiB 크기의 JSON 요청 본문을 사용했을 때도 413을 재현하지 못했으므로, 이전 설명처럼 prompt가 너무 길어서 발생한다는 해석은 지나치게 좁았습니다.

실제로 413이 발생한다면, 먼저 요청 크기 문제로 보세요. 일반적인 원인은 다음과 같습니다:

• 큰 base64 페이로드
• 인라인으로 포함된 과도하게 큰 이미지 또는 오디오
• 매우 큰 multipart 또는 JSON 본문

대응 방법:

1. 첨부된 콘텐츠를 줄이거나 압축합니다.
2. 큰 작업을 더 작은 요청으로 나눕니다.
3. 원인이 단순한 텍스트 길이뿐이라고 가정하지 마세요.

​

429 Too Many Requests

24개의 병렬 GET /v1/models 요청으로 수행한 제한적 동시성 점검에서는 429를 재현하지 못했으므로, 정확한 임계값은 route, model, 그리고 현재 플랫폼 상태에 따라 달라지는 것이 분명합니다.

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

1. 지터가 포함된 지수 백오프를 사용합니다.
2. 순간적인 동시 요청 수를 줄입니다.
3. 어떤 route와 model이 먼저 포화되는지 확인할 수 있도록 요청 로깅을 유지합니다.

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

​

500, 503, 504, 그리고 524

제한된 테스트에서는 이러한 상태 코드를 재현하지 못했습니다. 이들은 사용자 실수가 아니라 서버 측 또는 타임아웃 계열 실패로 문서화되어야 합니다.

실용적인 가이드는 다음과 같습니다:

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

대응 방법:

1. 백오프를 적용해 재시도합니다.
2. request id, endpoint, model, timestamp를 보관합니다.
3. 동일한 실패가 여러 번의 재시도 후에도 반복되면, 해당 정보를 포함해 support에 문의하세요.

​

지원팀에 문의하기 전에

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

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

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

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

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

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