블로그로 돌아가기

문제 해결가이드

흔한 연결 오류와 해결 방법

CheapTokens API에 연결할 때 401, 402, 400, 404, 413, 429, 503이 의미하는 것과 응답 형태, 각각의 해결 방법입니다.

작성자: CheapTokens Team 게시됨읽는 시간 3분

터미널에 짧은 설명과 함께 나열된 HTTP 상태 코드 401, 402, 400, 404, 429 목록
이 페이지의 내용
  1. 빠른 점검
  2. 401 — 잘못된 API 키
  3. 402 — 잔액 소진 또는 요청에 키 없음
  4. 404 — 잘못된 주소
  5. 400 — 모델을 찾을 수 없음
  6. 413 — 요청이 너무 큼
  7. 429 — 요청이 너무 많음
  8. 503 — 모델을 일시적으로 사용할 수 없음
  9. 긴 대기와 타임아웃

거의 모든 연결 문제는 네 가지로 귀결됩니다: 주소, 키, 모델 ID, 잔액입니다. 아래 빠른 점검부터 시작한 뒤 해당 상태 코드를 찾아보세요. 여기에 인용된 응답 본문은 API의 실제 응답입니다(2026년 10월).

빠른 점검#

bash
# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

첫 번째 명령이 실패하면 원인은 사용자 쪽 네트워크, 주소의 오타, 또는 서비스 자체의 일시적 사용 불가일 수 있습니다. 두 번째만 실패하면 아래에서 해당 상태 코드를 찾아보세요. 둘 다 작동하는데 도구가 작동하지 않으면 도구의 설정을 이 두 명령과 비교해 보세요.

401 — 잘못된 API 키#

json
{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Anthropic 스타일의 클라이언트는 같은 오류를 자기 형식으로 받습니다:

json
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

원인:

  • 키를 복사할 때 문자가 빠졌거나 공백 또는 따옴표가 포함됨;
  • 대시보드에서 키를 교체함 — 이전 키는 더 이상 작동하지 않음;
  • CheapTokens 키 대신 다른 서비스(예: OpenAI)의 키가 설정됨;
  • 이 터미널에서 환경 변수가 비어 있음: echo ${#CHEAPTOKENS_API_KEY}은 길이를 출력합니다.

대시보드는 키를 한 번만 표시합니다. 키를 잃어버렸다면 Rotate를 눌러 새 키를 받고 사용되는 모든 곳에서 갱신하세요.

402 — 잔액 소진 또는 요청에 키 없음#

API는 두 가지 상황에서 402를 반환합니다:

  1. 잔액이 소진됨. 요청은 잔액에서 결제되며, 잔액이 떨어지면 키가 일시 중지됩니다. 대시보드에서 충전하면 요청이 다시 통과됩니다.
  2. 요청에 키가 전혀 없음. Authorization 헤더(또는 Anthropic 스타일 클라이언트의 경우 x-api-key)가 없으면 API는 insufficient_funds 유형으로 402를 응답합니다. 도구가 실제로 키를 보내는지 확인하세요: OpenAI 스타일은 Authorization: Bearer <key>입니다.

404 — 잘못된 주소#

json
{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

경로에 오타가 있습니다 — 여기서는 completions 대신 completion입니다. 다른 흔한 원인:

  • base URL에 /v1이 없음. OpenAI 스타일 클라이언트에는 https://api.cheaptokens.dev/v1이 필요합니다. /v1이 없으면 요청이 API에 도달하지 못하고 JSON 대신 일반 HTML 404 페이지를 받습니다.
  • /v1이 두 번. 일부 클라이언트는 /v1을 스스로 추가하므로, 이때 base URL은 루트인 https://api.cheaptokens.dev이어야 합니다. Anthropic 스타일 클라이언트는 항상 루트 주소를 사용합니다.

400 — 모델을 찾을 수 없음#

json
{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

모델 ID는 슬래시 앞의 접두사를 포함한 전체 ID여야 합니다: deepseek-v4-flash가 아니라 deepseek-ai/DeepSeek-V4-Flash-0731입니다. 대소문자는 상관없습니다. 오류 메시지에 사용 가능한 ID가 나열되며, 전체 목록은 항상 GET /v1/models에 있습니다.

400은 잘못된 요청 본문에 대해서도 반환됩니다 — 예를 들어 빈 messages 배열(messages field is required and must be a non-empty array)이나 role이 없는 메시지입니다.

413 — 요청이 너무 큼#

요청 본문은 16 MB로 제한됩니다. 에이전트는 거대한 파일이나 로그를 컨텍스트에 넣어 이 한도에 도달할 수 있습니다. 모델에 필요한 부분만 보내고 긴 도구 출력은 잘라내세요.

429 — 요청이 너무 많음#

429를 받으면 속도를 늦추세요. 응답에는 기다려야 할 초 수를 담은 Retry-After 헤더가 포함됩니다. 공식 OpenAI SDK는 자동으로 재시도하며(max_retries), 직접 작성한 코드에서는 다음 시도 전에 Retry-After만큼 기다리세요.

503 — 모델을 일시적으로 사용할 수 없음#

모델이 일시적으로 사용 불가일 수 있으며, 이때 API는 model_unavailable 유형으로 503을 응답하고 사이트의 모델 카드에는 "temporarily unavailable"이 표시됩니다. 나중에 다시 시도하거나 model 필드를 다른 모델로 바꾸세요 — 키와 주소는 그대로입니다.

긴 대기와 타임아웃#

zai-org/GLM-5.3-Flash 같은 추론 모델은 답변 전에 생각하므로 첫 토큰이 오래 걸릴 수 있습니다. 스트리밍을 사용하거나 클라이언트 타임아웃을 늘리세요 — 예를 들어 OpenAI SDK에서 timeout=120입니다.

태그: