문제 해결
증상별 색인 — 현재 나타나는 증상을 찾아 원인으로 바로 이동하세요.
재시도 전에 액세스 확인
- 사용하려는 이용 권한이 활성화되어 있는지 확인하고 만료일을 기록하세요.
- 키가 사용하려는 그룹에 속해 있는지 확인하세요. 기간제 Claude 요금제는 다음을 사용합니다: Claude Unlimited; Codex 액세스는 별도입니다.
- 동일한 키로 모델 목록을 조회하고, 반환된 ID를 선택한 뒤 소규모 요청을 한 번 보내세요.
다음을 사용하세요: 모델 및 키 그룹 또는 다음을 참조하세요: 에이전트 설정 체크리스트 어느 단계에서 실패했는지 확실하지 않은 경우.
아무것도 작동하지 않는 경우
다른 문제를 디버깅하기 전에 기본 동작부터 확인하세요:
curl -s -o /dev/null -w "%{http_code}\n" https://aiprimetech.io/v1/models \
-H "Authorization: Bearer $CLAUDEAPIKEY"모델 목록 응답을 성공적으로 받은 뒤, 선택한 모델이 목록에 있는지 확인하고 소규모 생성 요청을 한 번 보내세요. 모델 가용성, 이용 권한, 제한 또는 클라이언트 설정 때문에 생성은 여전히 실패할 수 있습니다.
증상별
| 증상 | 가능성 높은 원인 | 해결 방법 |
|---|---|---|
404 모든 호출에서 | 기본 URL의 다음 항목이 잘못됨: /v1 처리 | 기본 URL |
401 방금 생성한 키를 사용할 때 | 형식에 맞지 않는 헤더 또는 끝에 붙은 공백 | 인증 |
402 | 크레딧이 없거나 요금제가 만료됨 | 충전 · 요금제 |
400 max_tokens | Messages에는 다음이 필요합니다: max_tokens; Chat Completions에는 필요하지 않습니다 | 메시지 |
model_not_found | 잘못된 ID, 잘못된 키 그룹 또는 해당 키로 사용할 수 없는 모델 | 모델 및 키 그룹 |
| 스트리밍은 연결되지만 아무것도 수신되지 않음 | 다른 형식의 이벤트 구조로 파싱함 | 스트리밍 |
| 응답이 문장 중간에서 끊김 | stop_reason: max_tokens | 늘리세요: max_tokens |
| curl에서는 작동하지만 SDK에서는 실패함 | SDK가 기본 URL에 자체 경로를 덧붙임 | 기본 URL |
| 대시보드에 사용량이 표시되지 않음 | 요청이 다른 키 또는 엔드포인트로 전송됨 | 확인할 항목: ANTHROPIC_API_KEY 설정되지 않음 — Claude Code |
빈번한 429 | 에이전트의 병렬 실행 수가 너무 많음 | 요청 속도 제한 |
| 청구 금액이 예상보다 높음 | 턴이 진행될수록 컨텍스트가 커짐 | 컨텍스트 관리 |
오류 본문 읽기
상태 코드는 문제의 유형을 알려주며, error.type 및 error.message 필드는 구체적으로 어떤 문제인지 알려줍니다. 본문 전체를 로그에 기록하세요 — 400 다음으로 바꾸세요: "missing max_tokens" 및 400 다음으로 바꾸세요: "invalid role" 에는 완전히 다른 해결 방법이 필요합니다.
여전히 해결되지 않는 경우
문의 support@aiprimetech.io 엔드포인트, 모델 ID, 상태 코드, 오류 본문을 함께 제공하세요. API 키는 절대 포함하지 마세요. 이미 어딘가에 붙여 넣었다면 먼저 폐기하세요.