오류와 제한

호출한 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 — 이전 클라이언트용입니다.

{
  "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 <key>\". 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. …"
}

{
  "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"
}

{
  "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"
      }
    ]
  }
}

모델 응답 및 결과 확인 코드(502, 503, 504)는 이제 모델 또는 요청을 가리킵니다: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed 및 result_pending_check. 코드에서 error.code 를 이전 값과 비교한다면 표의 새 코드로 바꾸세요. 이전 코드와 새 코드의 대응 관계는 다음에서 안내합니다: 지원.

• 먼저 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. 요청, 키 또는 잔액부터 수정하세요.

호출 빈도와 동시 요청 수는 키별이 아니라 계정 전체에 적용됩니다. 초과하면 429 rate_limit_exceeded 헤더: Retry-After: 10. 모델 자체가 과부하 상태이면 503 model_overloaded 및 Retry-After: 30. 더 많은 부하가 필요하다면 다음으로 문의하세요: 지원팀.

지출 한도는 키에 설정합니다. 전체 한도 — 402 api_key_quota_exhausted, 5시간·1일·7일 시간 창 — 429 usage_limit_reached. 자세한 내용: 키와 API 주소.

모델 목록은 잔액이 없어도 조회할 수 있습니다. 생성에는 예약 금액을 충당할 잔액이 필요합니다. NVIDIA 모델(Nemotron 등)은 공용 대기열을 사용합니다. 부하가 높으면 응답이 늦거나 Retry-After 헤더가 포함된 «모델 일시 과부하» 오류가 반환될 수 있습니다. 지정된 시간 뒤에 다시 시도하세요. 가격은 카탈로그에서 확인하며 차감은 다른 모델과 동일합니다.

크기 한도는 모델이 정합니다. 입력할 수 있는 토큰 수인 컨텍스트와 최대 응답 길이입니다. 확인 위치: 카탈로그.