API 오류

API 오류

이 페이지는 모든 Interactions API 오류 코드에 대한 참조를 제공하고, 오류 응답 형식을 설명하며, API가 다양한 요청 유형에 대해 오류를 전달하는 방식을 설명해요.

출처: 원문

본문

표준 API 오류 코드

이 일반 요청 수준 오류 코드는 표준 HTTP 상태 코드에 해당해요. 애플리케이션 로직에서 code 필드를 사용해 프로그래밍 방식으로 오류를 처리하세요.

생성 차단 코드

이 오류 코드는 정책, 안전 또는 콘텐츠 제한이 모델 출력을 차단했음을 나타내요. 이 코드 중 하나를 받으면 입력을 수정하고 다시 시도하세요.

생성 오류 코드

이 오류 코드는 모델의 생성 출력에 구조적 문제가 있음을 나타내요(예: 잘못된 함수 호출 또는 선언되지 않은 도구 호출).

오류 응답 형식

Interactions API의 모든 오류는 code와 message를 포함하는 error 객체를 반환해요. 예를 들어 지원되지 않는 도구 유형을 전달하면 다음과 같이 반환돼요.

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}

오류가 전달되는 방식

API는 표준 HTTP 요청을 하는지 스트리밍(SSE) 요청을 하는지에 따라 오류를 다르게 전달해요.

표준 HTTP 요청

표준(비스트리밍) 요청의 경우 API는 HTTP 응답 상태 코드(예: 400 Bad Request, 401 Unauthorized, 429 Too Many Requests)를 설정하고 JSON 응답 본문에 error 객체를 반환해요.

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

스트리밍(SSE) 요청

스트리밍 요청(stream: true)의 경우 API는 event_type을 "error"로 설정하여 Server-Sent Events(SSE) 스트림을 통해 오류 이벤트를 보내요. error 필드는 동일한 code와 message 구조를 포함해요.

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

전체 SSE 이벤트 스키마는 Interactions API 참조를 참조하세요.

다음 단계

• API 트러블슈팅: 일반적인 문제와 오류 시나리오 해결.
• 요금 한도: 요청 한도와 할당량 처리에 대해 알아보기.

더 알아보기 (Learn more)

• Interactions API 참조
• API 트러블슈팅
• 요금 한도