오류 레퍼런스

표준화된 오류 형식과 가장 흔한 오류 코드.

형식

엔드포인트와 관계없이 모든 오류는 동일한 JSON 구조를 따릅니다:

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "Solde de credits insuffisant ou budget mensuel du projet depasse.",
    "request_id": "9480fe92-f68e-4731-b98e-d35a5e8b9819",
    "details": {}
  }
}

request_id는 여러 서비스에 걸쳐 요청을 처음부터 끝까지 식별합니다 — 예기치 않은 오류로 문의하실 때 제공해 주시면 유용합니다.

자주 발생하는 코드

HTTP	코드	의미
401	missing_api_key	Authorization 헤더가 없습니다.
401	invalid_api_key	유효하지 않거나, 폐기되었거나, 만료된 API 키입니다.
403	insufficient_scope	이 카테고리에 필요한 범위를 키가 가지고 있지 않습니다.
403	not_a_member	귀하는 이 조직에 속해 있지 않습니다.
403	csrf_check_failed	보안 헤더가 누락되었습니다(세션 쿠키, API 키 사용 시에는 해당 없음).
404	model_not_found	routing_strategy "manual"에 카탈로그에 없는 model을 지정했습니다.
404	no_model_available	요청한 조건에 맞는 모델이 없습니다.
402	insufficient_credits	크레딧 잔액이 부족하거나 프로젝트의 월간 예산을 초과했습니다.
409	conflict	요청한 작업과 현재 상태가 호환되지 않습니다(예: 에이전트 대화가 idle 상태가 아님).
422	validation_error	요청 본문이 유효하지 않습니다(필드 누락, 잘못된 타입 등).
429	rate_limit_exceeded	이 키에 대한 요청이 너무 많습니다 — 속도 제한 문서를 참고하세요.
503	all_providers_unavailable	모든 후보 제공업체가 실패했습니다(라우팅 및 장애 조치 참고).

SDK에서

공식 SDK는 각 HTTP 상태 범위를 타입이 지정된 오류 클래스(AuthenticationError, PermissionDeniedError, NotFoundError, InsufficientCreditsError, ConflictError, ValidationError, RateLimitError, ServerError)로 변환하며, 모두 메시지 외에 .code, .status, .requestId, .details를 제공합니다. JavaScript SDK / Python SDK를 참고하세요.