오류와 재시도
오류와 요청 ID로 원인을 확인합니다.
HTTP 429는 로컬 수용 압력, 가득 찬 대기열 또는 상위 공급자 제한 때문일 수 있습니다. 오류와 Retry-After를 확인하세요. RPM/TPM 무제한을 의미하지 않습니다.
Retry-After를 따르고 지터가 있는 지수 백오프를 사용하며 횟수와 총시간을 제한하세요. 비디오 작업이 생성되었을 수 있다면 재전송 전에 ID로 조회하세요.
x-apivn-request-id가 있으면 오류 발생 시간과 함께 보관하세요. 보고서에 API 키나 민감한 내용을 넣지 마세요.
오류 코드
| HTTP | 오류 유형 | 원인 |
|---|---|---|
| 400 | invalid_request_error | JSON이 잘못되었거나 매개변수가 누락됨 |
| 401 | authentication_error | 키 누락, 키 오류 또는 폐기됨 |
| 402 | insufficient_balance api_key_monthly_limit outstanding_undercharge | error.type을 확인하세요. insufficient_balance는 사용 가능 잔액 부족, api_key_monthly_limit는 키의 월 지출 한도 도달, outstanding_undercharge는 이전 요청의 미정산 금액을 뜻합니다. 키 한도는 Dashboard → Keys에서 확인하세요. 지갑을 충전해도 키 한도는 자동으로 늘어나지 않습니다. |
| 403 | model_not_allowed | 이 API 키는 선택한 모델을 사용할 권한이 없습니다. Dashboard → Keys에서 모델 권한을 확인하거나 허용된 모델을 선택하세요. |
| 413 | request_too_large | 본문이 20 MB를 초과했거나 입력이 모델/제공자별 한도를 초과했습니다. 메시지를 읽고 문맥, 이미지 또는 파일을 줄이세요. 게이트웨이 한도 미만의 본문에도 413이 반환될 수 있습니다. |
| 429 | rate_limit_error | HTTP 429는 로컬 수용 압력, 가득 찬 대기열 또는 상위 공급자 제한 때문일 수 있습니다. 오류와 Retry-After를 확인하세요. RPM/TPM 무제한을 의미하지 않습니다. |
| 502 | api_error | 상류 공급자의 모델에 연결할 수 없음 |
| 503 | service_unavailable | 시스템 점검 중 |
잔액 오류에는 required_vnd와 available_vnd가, 키 한도 오류에는 limit_vnd와 spent_vnd가 포함될 수 있습니다. 확인을 위해 request ID와 함께 저장하되 API 키는 공유하지 마세요.
{
"type": "error",
"error": {
"type": "insufficient_balance",
"message": "잔액이 부족합니다. https://apivn.dev/dashboard/topup에서 충전하세요."
}
}문제 해결
x-apivn-request-id가 있으면 오류 발생 시간과 함께 보관하세요. 보고서에 API 키나 민감한 내용을 넣지 마세요.
Retry-After를 따르고 지터가 있는 지수 백오프를 사용하며 횟수와 총시간을 제한하세요. 비디오 작업이 생성되었을 수 있다면 재전송 전에 ID로 조회하세요.
| 증상 | 흔한 원인 | 처리 방법 |
|---|---|---|
| 404 또는 "Not Found" | /v1 접미사가 빠졌거나 불필요하게 포함된 잘못된 기본 URL을 붙여넣었습니다. | Anthropic 유형 도구는 https://apivn.dev을 사용하고, OpenAI 유형 도구는 https://apivn.dev/v1을 사용합니다. |
| 401 authentication_error | 잘못된 키, 이미 폐기된 키, 또는 앱이 이전에 저장한 키를 여전히 사용하고 있는 경우. | 제어판에서 새 키를 생성하고, 앱에서 이전 키를 삭제한 후 앱을 다시 시작하세요. |
| 402 insufficient_balance | 지갑 잔액이 부족합니다. | 충전 페이지에서 충전하세요. |
| 429 rate_limit_error | HTTP 429는 로컬 수용 압력, 가득 찬 대기열 또는 상위 공급자 제한 때문일 수 있습니다. 오류와 Retry-After를 확인하세요. RPM/TPM 무제한을 의미하지 않습니다. | Retry-After를 따르고 지터가 있는 지수 백오프를 사용하며 횟수와 총시간을 제한하세요. 비디오 작업이 생성되었을 수 있다면 재전송 전에 ID로 조회하세요. |
| Claude Code가 계속 로그인을 요청합니다. | 컴퓨터에 이전 Anthropic 계정 로그인 세션이 아직 남아 있습니다. | Claude Code에서 /logout을 실행하고 ANTHROPIC_AUTH_TOKEN을 설정한 뒤 터미널을 다시 여세요. |
| 앱에서 모델이 존재하지 않는다고 표시됩니다 | 모델 이름이 잘못 입력되었거나 앱이 자동으로 공급자 접두사를 추가합니다. | GET /v1/models를 호출해 정확한 이름을 확인하고, 앱에서 필요하지 않다면 anthropic/ 같은 접두사는 제거하세요. |
| 이미지 전송 시 오류가 발생합니다 | 앱이 모델이 지원하지 않는 형식으로 이미지를 보내거나, 이미지가 너무 큽니다. | Chỉ dùng model có nhãn Vision, nén ảnh và giữ toàn bộ yêu cầu dưới 20 MB. |
| 환경 변수가 작동하지 않습니다 | 기존 터미널은 이전 값을 그대로 유지하거나, 앱이 별도의 파일에서 구성을 읽습니다. | 새 터미널을 열어 주세요(Windows의 경우: 로그아웃 후 다시 로그인). 그런 다음 앱에 환경 변수를 덮어쓰는 설정 파일이 있는지 확인하세요. |
예제는 소스 검토와 로컬 점검 대상이며 모든 앱 버전의 실제 검증을 의미하지 않습니다. 운영 전에 설정, 작은 요청, 사용량을 확인하세요.