--- title: "오류 코드와 문제 해결" description: "1折AI를 호출할 때 401, 404, 429, 529, 5xx, 타임아웃 및 Claude Code 오류가 발생할 때의 원인과 해결 방법." headingIds: {"문제 해결 순서":"section-1","오류 코드 빠른 참조":"section-2","실제 측정 응답":"section-3","증상별 문제 해결":"section-4","401 / Invalid token":"section-5","404 / Invalid URL":"section-6","403 / error code: 1010":"section-7","429 너무 많은 요청":"section-8","529 / overloaded_error":"section-9","타임아웃, 스트리밍 중간에 끊김":"section-10","Claude Code: 로그인 화면으로 바로 진입":"section-11","Claude Code: Extra inputs are not permitted / context_management가 400 오류":"section-12","잔액은 충분한데 호출 실패":"section-13","제한된 재시도와 피드백 템플릿":"section-14","그래도 해결되지 않으면":"section-15"} --- 아래 체크리스트를 순서대로 확인해 보세요. 대부분의 문제는 앞의 세 단계에서 찾을 수 있습니다. ## 문제 해결 순서 1. **주소**: Anthropic 계열 도구에는 `https://1zheai.com`을, OpenAI 계열에는 `https://1zheai.com/v1`을 입력합니다. [Base URL 및 인증](/ko/docs/base-url/)을 참조하세요. 2. **API 키(API key)**: 완전한지(불필요한 공백, 줄바꿈 없음), 삭제되지 않았는지, 올바른 필드에 입력했는지 확인합니다. 3. **잔액**: 콘솔에서 잔액이 충분한지 확인합니다. 4. **모델 ID**: [지원 모델](/ko/docs/models/) 목록과 완전히 일치하는지 확인합니다. 5. **네트워크**: 프록시를 끄고 직접 연결로 다시 시도합니다. 6. **그래도 안 되면**: 최소한의 curl 재현 요청(아래 참조)을 만들어 응답과 시간을 보내주세요. ```bash title="最小复现" curl -i https://1zheai.com/v1/messages \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -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 | 게이트웨이 또는 상위 일시 장애 | 잠시 후 재시도; 지속 발생 시 support@1zheai.com으로 이메일 발송 | | 504 | 요청 타임아웃 | 긴 출력은 스트리밍 사용; 클라이언트 타임아웃 증가 | | 529 | 상위 Anthropic 과부하(`overloaded_error`) | 몇 초 기다렸다가 재시도하거나, 일시적으로 다른 모델로 전환 | Anthropic 공식 오류 유형(`invalid_request_error`, `authentication_error`, `rate_limit_error`, `overloaded_error` 등)의 전체 의미는[공식 Errors 문서](https://platform.claude.com/docs/en/api/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` 필드가 하나 더 있습니다. ```json title="401 API 密钥无效、禁用、过期或额度用完" {"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"} ``` ```json title="403 账户余额不足" {"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"} ``` ```json title="403 API 密钥没开通该模型" {"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"} ``` ```json title="403 IP 不在白名单" {"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"} ``` ```json title="400 上游参数错误" {"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"} ``` ```json title="404 路径不存在" {"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}} ``` 모델이 존재하지 않거나 사용 불가할 때의 404 설명은[지원 모델](/ko/docs/models/)을 참조하세요. 응답의 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 및 사용 가능 목록](/ko/docs/models/)을(를) 확인합니다. `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 연결](/ko/docs/quickstart-claude-code/)에서 환경 변수나 `settings.json`을(를) 확인합니다. ### Claude Code: Extra inputs are not permitted / context_management가 400 오류 Claude Code는 요청에 실험적인 beta 필드를 포함하며, 엄격한 상위가 인식하지 못하면 400 오류가 발생합니다. 아래 환경 변수를 설정하여 이를 끕니다(Claude Code 공식 LLM gateway 문서 출처): ```bash export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 ``` ### 잔액은 충분한데 호출 실패 - 특정 모델만 실패하는 경우, 해당 모델이 일시적으로 사용 불가이거나, ID를 잘못 입력했거나, 이 API 키에 모델 제한이 설정된 경우일 수 있습니다(403 `This token has no access to model …`). - 모두 실패하고 401인 경우, 이 API 키에 한도 상한이 설정되어 이미 소진되었거나 만료되었는지 확인합니다. 「API 키」 페이지의 「한도 ($)」 및 「만료」 열에서 볼 수 있습니다. - 그 외의 경우는 위의 오류 코드 표를 참조합니다. ## 제한된 재시도와 피드백 템플릿 무한 루프로 구성 오류를 감추지 마세요. SDK 타임아웃, 자동 재시도 횟수 및 백오프 처리는[타임아웃 및 재시도](/ko/docs/retries/)을(를) 참조하세요. 지원팀에 문의할 때 아래 템플릿을 복사하여, 키, 인증 헤더 및 개인 정보를 삭제한 후 발송하세요: ```text 发生时间与时区： 客户端及版本： 请求方法与完整路径： 模型 ID： HTTP 状态码： request id（如有）： 脱敏后的错误正文： 最小请求能否复现： 是否使用代理 / 是否仅某个模型失败： ``` ## 그래도 해결되지 않으면 support@1zheai.com으로 이메일을 보내주세요. 시간, 모델 ID, 사용한 도구와 버전, `curl -i`의 전체 출력(API 키 삭제)을 첨부해 주세요.