오류 코드와 문제 해결

1折AI를 호출할 때 401, 404, 429, 529, 5xx, 타임아웃 및 Claude Code 오류가 발생할 때의 원인과 해결 방법.

아래 체크리스트를 순서대로 확인해 보세요. 대부분의 문제는 앞의 세 단계에서 찾을 수 있습니다.

문제 해결 순서

주소: Anthropic 계열 도구에는 https://1zheai.com을, OpenAI 계열에는 https://1zheai.com/v1을 입력합니다. Base URL 및 인증을 참조하세요.
API 키(API key): 완전한지(불필요한 공백, 줄바꿈 없음), 삭제되지 않았는지, 올바른 필드에 입력했는지 확인합니다.
잔액: 콘솔에서 잔액이 충분한지 확인합니다.
모델 ID: 지원 모델 목록과 완전히 일치하는지 확인합니다.
네트워크: 프록시를 끄고 직접 연결로 다시 시도합니다.
그래도 안 되면: 최소한의 curl 재현 요청(아래 참조)을 만들어 응답과 시간을 보내주세요.

1
curl -i https://1zheai.com/v1/messages \
2
  -H "x-api-key: sk-你的Key" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

-i은(는) 상태 코드와 응답 헤더를 함께 출력하므로 문제 해결에 유용합니다.

오류 코드 빠른 참조

상태 코드	흔한 원인	조치
400	요청 본문 문제: 매개변수명 오류, 필드 타입 오류, `max_tokens`이(가) 모델 상한 초과, 상위에서 인식하지 못하는 beta 필드 포함	`message`에서 지적된 필드를 확인; Claude Code의 경우 아래 “Extra inputs are not permitted” 참조
401	API 키가 유효하지 않음, 삭제됨, 비활성화됨, 만료됨, 자체 한도 소진, 또는 누락되거나 잘못된 헤더에 배치됨	응답은 모두 `Invalid token`이므로 항목별로 확인; Anthropic 네이티브는 `x-api-key` 또는 `Authorization: Bearer` 사용
403	계정 잔액 부족(`billing_error` / `insufficient_quota`); 이 API 키로 해당 모델이 활성화되지 않음; 요청 IP가 이 API 키의 화이트리스트에 없음(모두 `permission_error`)	충전하거나, 「API 키」 페이지에서 이 API 키의 모델 제한 및 IP 화이트리스트를 편집
404	경로가 잘못되었거나, 모델이 존재하지 않음 / 현재 사용 불가	`Invalid URL`에서 주소 확인; `not_found_error` / `model_not_found`에서 모델 ID 및 사용 가능 목록 확인
413	요청 본문이 너무 큼	한 번에 전송하는 내용을 줄이고, 큰 파일은 분할
429	상위에서 일시적 속도 제한. 현재 API 키에 속도 제한을 두지 않음	잠시 후 재시도, 배치 작업은 지수 백오프 추가
503	모델은 존재하지만 일시적으로 건강한 상위 서비스가 없거나, 서비스 일시 장애	잠시 후 재시도; 지속 실패 시 요청 ID를 제공하여 지원팀에 문의
500 / 502	게이트웨이 또는 상위 일시 장애	잠시 후 재시도; 지속 발생 시 [email protected]으로 이메일 발송
504	요청 타임아웃	긴 출력은 스트리밍 사용; 클라이언트 타임아웃 증가
529	상위 Anthropic 과부하(`overloaded_error`)	몇 초 기다렸다가 재시도하거나, 일시적으로 다른 모델로 전환

Anthropic 공식 오류 유형(invalid_request_error, authentication_error, rate_limit_error, overloaded_error 등)의 전체 의미는공식 Errors 문서을 참조하세요.

상위에서 반환된 오류는 상태 코드와 message을(를) 그대로 전달하며, message 끝에 이번 요청의 request id를 추가합니다. /v1/messages을(를) 사용하면 외부는 공식의 {"type":"error","error":{...}} 구조이고, error.type은(는) 상태 코드에 따라 공식 유형을 채웁니다. /v1/chat/completions을(를) 사용하면 OpenAI의 {"error":{...}} 구조입니다.

실제 측정 응답

아래는 2026-10-15에 /v1/messages에 대해 실제 측정한 응답입니다. /v1/chat/completions을(를) 사용하면 내용은 동일하되, 외부에 "type":"error"이(가) 없고, error에 code 필드가 하나 더 있습니다.

{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}

{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}

{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}

{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}

{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}

{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}

모델이 존재하지 않거나 사용 불가할 때의 404 설명은지원 모델을 참조하세요. 응답의 request id는 이번 요청에 해당하며, 문제 제보 시 함께 첨부해 주세요.

증상별 문제 해결

401 / Invalid token

API 키 복사 시 공백이나 줄바꿈이 추가됨, 다시 복사합니다.
API 키가 콘솔에서 삭제되었거나 비활성화되었거나, 만료되었거나, 자체 한도가 소진됨. 이 경우들의 응답은 모두 동일한 Invalid token입니다.
Claude Code에서 ANTHROPIC_API_KEY과(와) ANTHROPIC_AUTH_TOKEN을(를) 동시에 설정했고 그중 하나가 이전 값인 경우: 둘 중 하나만 남기고, ANTHROPIC_AUTH_TOKEN을(를) 권장합니다.
settings.json의 env은(는) 터미널에서 export한 동일한 이름의 변수를 덮어쓰므로, 터미널 변수를 변경해도 반영되지 않을 때는 ~/.claude/settings.json을(를) 확인합니다.

404 / Invalid URL

먼저 오류 유형을 확인합니다: not_found_error 또는 model_not_found이면 모델 ID 및 사용 가능 목록을(를) 확인합니다. Invalid URL이면 /v1을(를) 확인합니다: OpenAI SDK, Cursor, Cline(OpenAI Compatible)은 https://1zheai.com/v1에 입력해야 하고, Claude Code와 Anthropic SDK는 https://1zheai.com만 입력하며, /v1을(를) 입력하면 /v1/v1/messages이(가) 됩니다.

403 / error code: 1010

응답에 error code: 1010 이 한 줄만 있고 JSON이 없으면, 요청이 게이트웨이 도달 전에 차단된 것입니다. 현재 Python 표준 라이브러리 urllib로 직접 요청을 보낼 때 발생하는 것으로 알려져 있습니다(기본 User-Agent는 Python-urllib/3.x). 요청 헤더에 자체 User-Agent을(를) 추가하거나, 공식 SDK, requests, httpx로 전환합니다.

429 너무 많은 요청

현재 API 키에 속도 제한을 두지 않습니다. 429를 받으면 보통 상위 부하가 높은 것이므로 잠시 후 재시도하면 됩니다. 배치 작업은 지수 백오프를 권장합니다: 실패 후 일정 시간 기다렸다가 재시도하고, 매번 대기 시간을 두 배로 늘리며, 자체적으로 큐로 동시성을 제어합니다.

529 / overloaded_error

상위 Anthropic이 일시적으로 과부하 상태이며, API 키나 잔액과는 무관합니다. 몇 초 기다렸다가 재시도하거나, 급할 경우 동일 계열의 다른 모델로 일시 전환합니다.

타임아웃, 스트리밍 중간에 끊김

긴 답변은 가능하면 스트리밍("stream": true)을 사용하며, 중간 네트워크 장비에 의해 끊기지 않습니다.
Claude Code는 API_TIMEOUT_MS로 타임아웃을 늘릴 수 있으며, 기본값은 600000(10분)입니다.
프록시를 켜둔 경우 먼저 프록시를 끄고 시도해 보세요. 많은 끊김은 프록시 노드에서 발생합니다.

Claude Code: 로그인 화면으로 바로 진입

Claude Code가 API 키를 읽지 못한 것입니다. Claude Code에서 /status을(를) 실행하여 base URL과 자격 증명 출처 두 줄을 확인합니다. 비어 있으면 Claude Code 연결에서 환경 변수나 settings.json을(를) 확인합니다.

Claude Code: Extra inputs are not permitted / context_management가 400 오류

Claude Code는 요청에 실험적인 beta 필드를 포함하며, 엄격한 상위가 인식하지 못하면 400 오류가 발생합니다. 아래 환경 변수를 설정하여 이를 끕니다(Claude Code 공식 LLM gateway 문서 출처):

1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

잔액은 충분한데 호출 실패

특정 모델만 실패하는 경우, 해당 모델이 일시적으로 사용 불가이거나, ID를 잘못 입력했거나, 이 API 키에 모델 제한이 설정된 경우일 수 있습니다(403 This token has no access to model …).
모두 실패하고 401인 경우, 이 API 키에 한도 상한이 설정되어 이미 소진되었거나 만료되었는지 확인합니다. 「API 키」 페이지의 「한도 ($)」 및 「만료」 열에서 볼 수 있습니다.
그 외의 경우는 위의 오류 코드 표를 참조합니다.

제한된 재시도와 피드백 템플릿

무한 루프로 구성 오류를 감추지 마세요. SDK 타임아웃, 자동 재시도 횟수 및 백오프 처리는타임아웃 및 재시도을(를) 참조하세요.

지원팀에 문의할 때 아래 템플릿을 복사하여, 키, 인증 헤더 및 개인 정보를 삭제한 후 발송하세요:

1
发生时间与时区：
2
客户端及版本：
3
请求方法与完整路径：
4
模型 ID：
5
HTTP 状态码：
6
request id（如有）：
7
脱敏后的错误正文：
8
最小请求能否复现：
9
是否使用代理 / 是否仅某个模型失败：

그래도 해결되지 않으면

[email protected]으로 이메일을 보내주세요. 시간, 모델 ID, 사용한 도구와 버전, curl -i의 전체 출력(API 키 삭제)을 첨부해 주세요.