블로그로 돌아가기

문제 해결가이드

API 401 또는 404 오류: 잘못된 키, base URL 또는 모델 id

상태 코드를 읽고, 세 가지 중 무엇이 잘못되었는지(키, base URL, 모델 id) 찾아내고, curl 요청 하나로 수정을 확인하세요.

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

상태 401과 키, base URL, 모델 id를 확인하라는 힌트가 있는 오류 카드
이 페이지의 내용
  1. 둘을 구별하는 빠른 방법
  2. 401: 키가 엔드포인트와 맞지 않음
  3. 모든 모델에서 404: 주소가 잘못됨
  4. 한 모델에서 404: 모델 id
  5. curl 명령 하나로 수정을 증명하기
  6. 그래도 작동하지 않는다면

요청이 상태 코드와 함께 실패했는데 무엇부터 손봐야 할지 모르겠다면. 짧은 답: 401은 보통 키를 가리키고, 404는 보통 잘못된 곳을 두드리고 있다는 뜻입니다 — 주소(base URL과 경로) 또는 모델 id 중 하나입니다. 이 순서대로 확인할 세 가지, 그리고 수정을 증명하는 curl 명령 하나.

OpenAI의 error-codes 페이지(2026년 10월 26일 확인)에는 두 가지 401 메시지가 있습니다: "Invalid Authentication"과 "Incorrect API key provided". 두 경우 모두 제시하는 해결책은 같습니다: 키를 확인하거나 새로 생성하세요. 이 페이지는 API 자체에 대한 404를 문서화하지 않으므로, 404에 대한 아래 규칙은 그 페이지가 아니라 OpenAI 호환 엔드포인트가 작동하는 방식에서 나옵니다.

둘을 구별하는 빠른 방법#

상태 서버가 하는 말 먼저 볼 것
401 보통: 이 키는 받지 않는다 키, 그리고 어느 제공자의 것인지
모든 모델에서 404 보통: 이 주소에는 아무것도 없다 base URL과 /v1
한 모델에서만 404 보통: 주소는 맞고, 이 모델 id를 모른다 모델 id

메시지의 문구는 서버와 도구에 따라 다릅니다(Cline, Aider, OpenCode, Continue는 각자 방식으로 오류를 감쌉니다). 그러니 숫자부터 시작하고, 아래 curl 확인으로 확정하세요.

401: 키가 엔드포인트와 맞지 않음#

전형적인 이야기: 도구를 새 제공자로 옮기고 base URL을 바꿨는데, 예전 제공자의 키를 설정에 그대로 두었습니다. 주소는 새것, 키는 예전 것, 서버는 401로 답합니다. 아무것도 고장 나지 않았습니다. 키가 다른 집에 속할 뿐입니다.

확인할 것:

  1. 키를 발급한 제공자는 어디인가? 호출하는 주소의 제공자여야 합니다. 한 서비스의 키는 다른 서비스에서 유효하지 않습니다.
  2. 불필요한 문자. 키와 함께 붙여넣은 공백이나 줄 바꿈, 또는 값 안에 들어간 따옴표.
  3. 도구가 키를 읽는 위치. 한 터미널에서는 설정되었지만 편집기가 시작된 터미널에서는 설정되지 않은 환경 변수가 흔한 원인입니다. 도구에 설정 파일과 환경 변수가 모두 있다면 어느 쪽이 우선하는지 확인하세요.
  4. 폐기되거나 삭제된 키. 삭제하거나 폐기한 키는 작동을 멈춥니다 — 새로 만들어 설정에 넣으세요.

키가 어떻게 작동하는지, 어디에 보관해야 하는지 확실하지 않다면, API 키란 무엇이고 안전하게 보관하는 방법에서 쉬운 말로 다룹니다.

모든 모델에서 404: 주소가 잘못됨#

CheapTokens의 base URL은 https://api.cheaptokens.dev/v1입니다. 도구와 SDK는 엔드포인트 경로를 스스로 붙이므로, 흔한 실수는 /v1에 관한 것입니다:

  • /v1 누락: 도구가 결국 https://api.cheaptokens.dev/chat/completions를 호출합니다.
  • /v1 중복: 이미 붙이는 필드에 전체 경로를 붙여넣어 https://api.cheaptokens.dev/v1/v1/chat/completions이 됩니다.
  • 잘못된 종류: OpenAI 스타일 도구와 OpenAI SDK는 /v1이 포함된 주소를 받습니다. Anthropic SDK와 Claude Code는 /v1 없이 주소를 받습니다: https://api.cheaptokens.dev.

base URL이 정확히 무엇이고 도구가 어느 부분을 붙이는지 궁금했다면, 이 설명이 짚어줍니다. Anthropic 쪽은 CheapTokens와 함께 쓰는 Anthropic Python SDK를 보세요.

한 모델에서 404: 모델 id#

이것은 가격표나 다른 제공자에서 이름을 복사하는 사람을 잡습니다. 가격표에는 DeepSeek-V4-Flash이라고 적혀 있을 수 있지만, API는 개발자 접두사와 릴리스가 포함된 전체 게이트웨이 id를 원합니다:

본 곳 API가 필요한 것
DeepSeek-V4-Flash deepseek-ai/DeepSeek-V4-Flash-0731
GLM-5.3-Flash zai-org/GLM-5.3-Flash
MiniMax-M2.7 MiniMaxAI/MiniMax-M2.7

가격 라벨의 짧은 id는 API가 받지 않으며, 철자가 중요합니다: 대문자, 슬래시, -0731 접미사. 기억에서 입력하지 말고 CheapTokens 문서에서 id를 복사하세요 — 제공자마다 같은 모델을 다르게 부릅니다. 키로 사용할 수 있는 정확한 id를 보려면, 같은 Authorization 헤더로 GET https://api.cheaptokens.dev/v1/models을 호출하고 목록에서 id를 복사하세요:

bash
curl https://api.cheaptokens.dev/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

표의 이름 규칙이 이상해 보인다면, AI 모델 이름 읽는 방법에서 별칭과 고정 버전을 설명합니다.

curl 명령 하나로 수정을 증명하기#

도구를 빼고 API를 직접 호출하세요. 키 자리 표시자를 자신의 것으로 바꾸세요:

bash
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
    "messages": [{"role": "user", "content": "Say hi in one word."}],
    "max_tokens": 20
  }'

이 요청 하나에 세 용의자가 모두 들어 있습니다: 헤더의 키, 첫 줄의 base URL, 본문의 모델 id. choices 배열이 담긴 JSON 응답이 오면 셋 다 맞다는 뜻이고, 도구가 다르게 하는 것이 문제입니다. 실패한다면 한 번에 하나씩 바꾸세요:

  • 401 → CheapTokens에서 받은 키로 바꿔 다시 실행하세요.
  • 404 → URL을 위의 것과 문자 하나씩 비교한 다음, 모델 id를 비교하세요.

curl이 작동하면 같은 세 값을 도구에 복사하세요: 키, base URL(https://api.cheaptokens.dev/v1, 또는 Anthropic SDK와 Claude Code의 경우 /v1 없이) 그리고 전체 모델 id.

그래도 작동하지 않는다면#

  • 도구에서 같은 오류, curl은 정상. 도구가 다른 곳에서 예전 키나 URL을 읽고 있습니다: 두 번째 설정 파일, 저장된 프로필, 환경 변수. 변경 후 도구를 재시작하세요.
  • 모델 id가 맞는지 확실하지 않음. 키로 GET /v1/models을 호출하고 목록에서 id를 복사하세요.
  • 연결 거부, 타임아웃, 인증서 오류. 그것은 401이나 404가 아닙니다; 흔한 연결 오류를 보세요.
  • 첫 요청이 어떤 모습이어야 하는지 확실하지 않음. 첫 API 요청이 단계별로 안내하고, 문서에 전체 레퍼런스가 있습니다.

유지할 만한 습관: 호출이 실패하면 숫자부터 읽으세요. 401은 보통 키, 404는 보통 주소나 모델 id를 뜻하며, curl이 확정해 줍니다. 이렇게 하면 로그를 하나 열기도 전에 이런 오류 대부분이 정리됩니다.

태그: