메인 콘텐츠로 건너뛰기

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 오류 처리는 요청 형식 문제, 인증 문제, 경로 실수, 재시도 가능한 플랫폼 장애를 구분하면 가장 쉽게 할 수 있습니다. 요청을 수정할지 재시도할지 결정할 때는 HTTP status, error.code, error.message를 함께 확인하세요.

​
빠른 분류

Status일반적인 의미재시도?첫 번째 조치
400요청이 정상적으로 처리되기 전에 요청 검증에 실패했습니다.아니요model, messages, JSON 형식, 필드 타입을 검증하세요.
401API 키가 없거나, 형식이 잘못되었거나, 유효하지 않습니다.아니요Authorization: Bearer <COMETAPI_KEY>를 확인하세요.
403접근이 차단되었거나 현재 요청이 허용되지 않았습니다.보통 아니요정상 작동이 확인된 요청으로 다시 시도하고, 먼저 모델별 필드를 제거하세요.
Path mistakebase URL 또는 endpoint path가 잘못되었습니다. Comet에서는 이것이 깔끔한 JSON 404가 아니라 301 리디렉션이나 HTML로 나타날 수 있습니다.아니요정확히 https://api.cometapi.com/v1를 사용하고, 디버깅 중에는 자동 리디렉션 따라가기를 비활성화하세요.
429속도 제한 또는 일시적 포화 상태입니다.예지터가 포함된 지수 백오프를 사용하세요.
500 with error.code: invalid_request잘못된 요청이 서버 status 응답을 통해 노출된 경우입니다.아니요재시도하기 전에 요청 본문을 수정하세요.
500, 503, 504, 524플랫폼, provider 또는 timeout 계열 장애입니다.예백오프와 함께 재시도하고 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 필드가 누락된 경우 error.code: invalid_request를 포함한 500으로 나타날 수도 있습니다.

​
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가 있으면 요청 문제로 처리하세요:
  1. 요청 본문을 수정합니다.
  2. payload를 endpoint schema와 비교합니다.
  3. payload를 수정한 후에만 재시도합니다.
500 응답이 잘못된 요청을 가리키지 않는다면 request id를 보관하고 백오프를 사용하세요.

​
401 Invalid Token

토큰 실패는 보통 다음과 같이 나타납니다: 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
확인할 사항:
  1. 헤더는 반드시 정확히 Authorization: Bearer <COMETAPI_KEY> 여야 합니다.
  2. 앱이 .env, 셸 히스토리 또는 배포된 시크릿 스토어에서 오래된 키를 불러오고 있지 않은지 확인하세요.
  3. 동일한 요청에서 한 키는 실패하고 다른 키는 동작한다면, 이를 endpoint 문제가 아니라 토큰 문제로 판단하세요.

​
403 Forbidden

403은 대부분 다음 상황 중 하나입니다:
  • 요청이 WAF 필터링과 같은 플랫폼 측 규칙에 의해 차단됨
  • token 또는 route가 요청한 model 또는 요청 형식을 사용할 수 없음
  • 선택한 model이 전달한 고급 parameter 중 하나를 거부함
먼저 할 일:
  1. 정상 동작이 확인된 model에 대해 매우 단순한 텍스트 요청으로 다시 시도하세요.
  2. 고급 필드와 provider별 parameter를 제거한 뒤, 점진적으로 다시 추가하세요.
  3. 응답에 request id가 포함되어 있다면 support에 문의하기 전에 이를 보관하세요.
메시지에 group 또는 channel 같은 내부 용어가 언급되면, 이를 클라이언트 측에서 가장 먼저 진단해야 할 대상으로 보지 말고 라우팅 세부 정보로 간주하세요. 실제로는 여전히 token, model, 요청 형식을 먼저 검증하는 것이 실질적인 해결 방법입니다.

​
잘못된 base URL 또는 잘못된 path

Comet에서는 path 오류가 다음과 같이 나타날 수 있습니다:
  • 리디렉션
  • 클라이언트가 리디렉션을 따를 경우 JSON이 아닌 HTML 응답
  • SDK 내부의 파싱 오류
  • API 레이어에 요청이 정상적으로 도달하지 못하는 상황
다음 base URL을 정확히 사용하세요: 
https://api.cometapi.com/v1
권장 확인 사항:
  1. base URL에 /v1이 포함되어 있는지 확인하세요.
  2. endpoint path가 문서와 정확히 일치하는지 확인하세요.
  3. path 문제를 디버깅하는 동안 자동 리디렉션 따라가기를 비활성화하세요.

​
413 Request Entity Too Large

413이 표시되면, 우선 요청 크기 문제로 간주하세요. 흔한 원인은 다음과 같습니다:
  • 큰 base64 payload
  • 인라인으로 포함된 과도하게 큰 이미지 또는 오디오
  • 매우 큰 multipart 또는 JSON body
해야 할 일:
  1. 첨부된 콘텐츠의 크기를 줄이거나 압축하세요.
  2. 큰 작업을 더 작은 요청으로 나누세요.
  3. 일반 텍스트 길이만이 유일한 원인이라고 가정하지 마세요.

​
429 Too Many Requests

429는 재시도 가능한 것으로 간주하세요:
  1. 지터를 포함한 지수 백오프를 사용하세요.
  2. 순간적인 동시성 폭주를 줄이세요.
  3. 어떤 route와 model이 먼저 포화되는지 확인할 수 있도록 요청 로깅을 유지하세요.
재사용 가능한 재시도 패턴은 채팅 완성의 백오프 예제를 참고하세요.

​
503, 504, and 524

이 상태 코드는 서버 측 또는 타임아웃 계열 실패입니다. 실용적인 가이드:
  • 503: route 또는 provider 서비스가 일시적으로 사용 불가
  • 504 및 524: 플랫폼, edge 또는 provider 서비스 사이에서 발생한 타임아웃 계열 실패
해야 할 일:
  1. 백오프와 함께 재시도하세요.
  2. request id, endpoint, model, 타임스탬프를 기록해 두세요.
  3. 동일한 실패가 여러 번의 재시도에서도 반복되면, 해당 맥락과 함께 support에 문의하세요.

​
지원팀에 문의하기 전에

먼저 다음 세부 정보를 수집하세요:
  • HTTP 메서드
  • Endpoint 경로
  • Model ID
  • 민감한 정보를 제거한 요청 본문 JSON (대부분의 API 호출에서 가장 유용한 단일 항목입니다)
  • 실패한 요청에서 사용한 경우 쿼리 파라미터
  • 클라이언트가 캡처했다면 정확한 응답 본문
  • 전체 HTTP 상태
  • 정확한 error.message
  • 모든 request id
  • 대략적인 타임스탬프
  • 동일한 요청이 다른 model 또는 다른 토큰으로는 동작하는지 여부
실패한 route가 일반 JSON 본문 대신 파일 업로드(이미지 편집, 오디오 업로드, 비디오 생성 등)를 받는 경우, 이에 해당하는 제출 payload를 보내주세요:
  • 파일과 함께 전송한 필드 이름과 텍스트 값
  • 파일 이름, 파일 유형, 대략적인 파일 크기
  • 파일을 직접 업로드했는지, URL로 참조했는지, 또는 base64로 포함했는지 여부
버그를 재현하는 가장 효과적인 방법은 정확하게 민감한 정보를 제거한 요청 payload입니다. 대부분의 API 호출에서는 원시 요청 본문 JSON을 의미합니다. 파일 업로드 route의 경우에는 필드 목록과 파일 메타데이터를 의미합니다.
이렇게 하면 지원 처리 시간이 크게 단축됩니다.