Source: https://ailoot.ai/docs/ko/errors/ Canonical: https://ailoot.ai/docs/ko/errors/ Language: ko [도움말](https://ailoot.ai/docs/ko/) # 오류와 제한 [Markdown](https://ailoot.ai/docs/ko/errors/index.md) 응답 코드의 의미와 해결 방법입니다. 모든 오류는 JSON으로 반환되며 Request ID를 포함합니다. ## [](https://ailoot.ai/docs/ko/errors/#format)오류 형식 호출한 API의 형식으로 오류를 반환합니다. 객체 `error` — OpenAI, `{"type": "error", "error": {...}}` — Anthropic 및 `error` — 다음 필드가 포함된 `status` 및 `details` — Gemini 형식입니다. 따라서 SDK는 일반 API 오류로 인식합니다. - `error.code` 및 `error.reason` — 아래 표의 오류 분류와 동일한 값입니다. `error.type` — 형식의 표준 값입니다(예: `invalid_request_error` 또는 `server_error`). - `error.request_id` (Anthropic에서는 `request_id` 최상위 필드), 헤더 `X-Request-ID` 및 메시지 끝부분에 요청 식별자가 표시됩니다. - Gemini 오류 분류 필드: `error.details`: `ErrorInfo.reason` — 동일 코드를 대문자로 표시합니다(예: `MODEL_OVERLOADED`), `domain` — `ailoot.ai`; 요청 식별자 필드: `RequestInfo.requestId`. - Gemini 형식에서 자동 재시도하면 안 되는 5xx 오류와 `result_pending_check` 는 상태 409 및 `status` `ABORTED`: Gemini SDK와 CLI의 자동 재시도를 방지합니다. 오류 분류 필드: `ErrorInfo.reason` (예: `MODEL_TIMEOUT` 또는 `RESULT_PENDING_CHECK`). - OpenAI 형식 응답에는 다음 최상위 필드도 있습니다: `code` 및 `message` — 이전 클라이언트용입니다. ```json { "code": "API_KEY_REQUIRED", "error": { "code": "invalid_api_key", "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer \". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.", "param": null, "reason": "invalid_api_key", "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6", "type": "invalid_request_error" }, "message": "No API key was sent with the request. Nothing was charged. …" } ``` ```json { "type": "error", "error": { "type": "authentication_error", "code": "invalid_api_key", "reason": "invalid_api_key", "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e." }, "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e" } ``` ```json { "error": { "code": 401, "status": "UNAUTHENTICATED", "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "INVALID_API_KEY", "domain": "ailoot.ai", "metadata": { "code": "invalid_api_key", "reason": "invalid_api_key", "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b" } }, { "@type": "type.googleapis.com/google.rpc.RequestInfo", "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b" } ] } } ``` “Nothing was charged”는 금액이 차감되지 않았다는 뜻입니다. X-Should-Retry: false를 받으면 자동 재시도하지 말고 먼저 내역에서 Request ID를 확인하세요. ## [](https://ailoot.ai/docs/ko/errors/#codes)오류 코드 | HTTP | 분류(reason) | 발생한 문제 | 해결 방법 | | --- | --- | --- | --- | | 400 | `invalid_request` | 잘못된 요청: 본문 또는 매개변수 오류, 모델이 요청 필드·첨부·도구를 지원하지 않음, 주소로 키 전송 | 오류 메시지에 따라 요청을 수정하세요. 미지원 필드·첨부·도구를 제거하고 키는 헤더로 보내세요. 미지원 항목으로 인한 거부는 금액 예약 전에 발생하므로 아무 금액도 차감되지 않습니다 | | 400 | `context_length_exceeded` | 요청이 모델 컨텍스트보다 김 | 대화 기록을 줄이거나 더 큰 컨텍스트의 모델을 선택하세요 | | 400 | `content_policy_violation` | 모델 규칙에 의해 요청 거부 | 요청을 다시 작성하세요 | | 401 | `invalid_api_key` | 키 누락 또는 잘못된 키 | 키가 완전하게 전달됐는지 확인하세요 | | 401 | `api_key_disabled` | 키 비활성화 | 키를 활성화하거나 새 키를 만드세요 | | 402 | `insufficient_balance`, `insufficient_quota` | 최소 예약액도 충당하지 못하는 가용 잔액(`insufficient_quota` — OpenAI SDK에 익숙한 형식으로 표시한 동일 상황) | 잔액을 충전하거나 max\_tokens를 줄이세요 | | 402 | `api_key_quota_exhausted` | 키 전체 지출 한도 소진 | 대시보드에서 키 한도를 늘리세요 | | 402 | `payment_disputed` | 이의 제기된 결제로 인한 계정 채무 | 상환 전까지 새 요청이 중지됩니다. 지원팀에 문의하세요 | | 403 | `api_key_expired` | 키 만료 | 새 키를 만드세요 | | 403 | `account_inactive` | 계정 비활성화 | 지원팀에 문의하세요 | | 403 | `permission_denied` | 키에 해당 요청이 허용되지 않음(예: IP 제한) | 키 제한을 확인하세요 | | 404 | `model_not_found` | 존재하지 않는 모델 | /v1/models의 ID와 비교하세요 | | 404 | `unsupported_endpoint` | 이 형식에서 모델이 작동하지 않음 | 다른 형식 또는 모델을 선택하세요 | | 404 | `not_found` | 존재하지 않는 경로 또는 객체(예: 작업) | 주소와 식별자를 확인하세요 | | 409 | `duplicate_request` | 동일 멱등성 키의 작업이 이미 접수됐으며 완료됐을 수 있음 | 첫 작업의 결과를 확인하고 새 작업을 보내지 마세요 | | 409 | `not_ready`, `video_not_ready` | 영상 또는 기타 작업이 아직 준비되지 않음 | 나중에 상태를 조회하세요 | | 409, 503 | `result_pending_check` | 요청 결과를 확인 중입니다. 영상 작업의 경우 다음 플래그가 `result_pending_check: true` 상태 응답에 있으며 작업 자체의 상태는 `in_progress` | 요청을 다시 보내지 마세요. 상태는 내역(GET https://ailoot.ai/api/v1/usage)에 표시됩니다. 영상 작업을 다시 만들지 말고 나중에 GET /v1/videos/{id}로 확인하세요 | | 410 | `model_retired` | 모델 서비스 종료 | GET /v1/models에서 새 버전을 선택하세요 | | 413 | `request_too_large` | 요청 본문이 너무 큼 | 파일 또는 대화 기록을 줄이세요 | | 429 | `rate_limit_exceeded`, `gateway_concurrency_limit`, `gateway_queue_full` | 계정의 요청 또는 동시 요청이 너무 많음 | 다음 헤더의 시간만큼 기다리세요: `Retry-After`(보통 10초). 이후 다시 시도하세요 | | 429 | `usage_limit_reached` | 키 지출 시간 창 소진(5시간, 1일 또는 7일) | 시간 창이 갱신될 때까지 기다리거나 키 한도를 늘리세요 | | 500 | `internal_error` | Ailoot 오류 | Request ID와 함께 지원팀에 문의하세요 | | 502 | `invalid_model_response`, `empty_response`, `incomplete_response` | 모델이 잘못되거나 비어 있거나 불완전한 응답을 반환함 | 계정 화면의 기록에서 Request ID를 찾으세요. 결과나 차감 내역이 있다면 재시도는 두 번째 유료 요청을 생성합니다. 기록이 없다는 사실만으로 요청이 전송되지 않았거나 실행되지 않았다고 확인할 수는 없습니다. 전송 여부가 불명확한 요청은 다시 보내지 말고 Request ID와 함께 고객 지원에 문의하세요. | | 502 | `result_not_delivered` | Ailoot의 책임으로 결과가 전달되지 않아 예약액 또는 차감액 반환 | 요청을 다시 보낼 수 있습니다 | | 503 | `model_overloaded` | 모델 일시 과부하 | X-Should-Retry: true이면 Retry-After초 뒤에 다시 시도하세요. false이면 먼저 내역에서 Request ID를 확인하세요 | | 503 | `model_unavailable` | 모델 일시 이용 불가 | 다른 모델을 선택하세요. X-Should-Retry: true이면 Retry-After초 뒤에 다시 시도하고, false이면 먼저 내역에서 Request ID를 확인하세요 | | 503 | `service_unavailable` | Ailoot 측 일시적 오류 | X-Should-Retry: true이면 Retry-After초 뒤에 다시 시도하세요. false이면 먼저 내역에서 Request ID를 확인하세요 | | 503 | `charge_not_confirmed` | 차감 확인에 실패해 응답을 전달하지 못함. 예약액은 반환됐고 금액은 차감되지 않음 | X-Should-Retry: true이면 Retry-After초 뒤에 다시 시도하세요. false이면 먼저 내역에서 Request ID를 확인하세요 | | 504 | `model_timeout` | 모델이 제시간에 응답하지 않았지만 결과가 나중에 나타날 수 있음 | 내역에서 Request ID를 확인하기 전에는 요청을 다시 보내지 마세요 | 모델 응답 및 결과 확인 코드(502, 503, 504)는 이제 모델 또는 요청을 가리킵니다: `model_unavailable`, `model_timeout`, `invalid_model_response`, `incomplete_response`, `charge_not_confirmed` 및 `result_pending_check`. 코드에서 `error.code` 를 이전 값과 비교한다면 표의 새 코드로 바꾸세요. 이전 코드와 새 코드의 대응 관계는 다음에서 안내합니다: [지원](https://ailoot.ai/docs/ko/support/). ## [](https://ailoot.ai/docs/ko/errors/#retry)재시도 조건 - **먼저 X-Should-Retry를 확인하세요**: 자동 재시도하지 말아야 할 조건은 다음과 같습니다 — `false`, `result_pending_check` 또는 `model_timeout` — 첫 번째는 헤더 값이고, 나머지 두 개는 오류 유형입니다. 대시보드 내역에서 Request ID로 결과와 차감액을 확인하세요. - **X-Should-Retry: true를 받은 경우 재시도가 안전합니다**: 다음 값만큼 기다리세요: `Retry-After` 초. 5xx는 코드만으로 판단하면 안 됩니다. 결과가 이미 나왔을 수 있습니다. 대시보드 내역을 확인하거나 Request ID와 함께 지원팀에 문의하세요. 이미지, 영상, 음악 및 긴 에이전트 단계에서는 특히 중요합니다. - **재시도해도 해결되지 않는 코드**: 400, 401, 402, 403, 404. 요청, 키 또는 잔액부터 수정하세요. OpenAI와 Anthropic SDK는 보통 네트워크 오류와 5xx를 자동 재시도합니다. 생성 요청에서는 다음으로 이를 끄고(`max_retries=0`) 다음을 확인하세요: `X-Should-Retry` — 새 시도 전에 확인해야 합니다. 응답을 잃었다고 요청이 실행되지 않았다는 뜻은 아닙니다. ## [](https://ailoot.ai/docs/ko/errors/#limits)제한 호출 빈도와 동시 요청 수는 키별이 아니라 계정 전체에 적용됩니다. 초과하면 429 `rate_limit_exceeded` 헤더: `Retry-After: 10`. 모델 자체가 과부하 상태이면 503 `model_overloaded` 및 `Retry-After: 30`. 더 많은 부하가 필요하다면 다음으로 문의하세요: [지원팀](https://ailoot.ai/docs/ko/support/). 지출 한도는 키에 설정합니다. 전체 한도 — 402 `api_key_quota_exhausted`, 5시간·1일·7일 시간 창 — 429 `usage_limit_reached`. 자세한 내용: [키와 API 주소](https://ailoot.ai/docs/ko/keys/#key). ## [](https://ailoot.ai/docs/ko/errors/#nvidia)NVIDIA 모델: 대기열 모델 목록은 잔액이 없어도 조회할 수 있습니다. 생성에는 예약 금액을 충당할 잔액이 필요합니다. NVIDIA 모델(Nemotron 등)은 공용 대기열을 사용합니다. 부하가 높으면 응답이 늦거나 Retry-After 헤더가 포함된 «모델 일시 과부하» 오류가 반환될 수 있습니다. 지정된 시간 뒤에 다시 시도하세요. 가격은 카탈로그에서 확인하며 차감은 다른 모델과 동일합니다. 크기 한도는 모델이 정합니다. 입력할 수 있는 토큰 수인 컨텍스트와 최대 응답 길이입니다. 확인 위치: [카탈로그](https://ailoot.ai/models/ko/). ## 내역과 비용 [내역과 비용](https://ailoot.ai/usage) · [GET https://ailoot.ai/api/v1/usage](https://ailoot.ai/docs/ko/cabinet/usage/) · JWT · `Authorization: Bearer $TOKEN` `JWT ≠ sk-…` · [로그인과 세션](https://ailoot.ai/docs/ko/cabinet/auth/) 궁금한 점이 남았나요? Request ID와 설명을 보내 주시면 해결을 도와드리겠습니다.[지원팀에 문의](mailto:support@ailoot.ai) ## Ailoot · 회사와 그 프로젝트 포트폴리오 Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다. 회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출. Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.