API 오류

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

표준 API 오류 코드

이러한 일반적인 요청 수준 오류 코드는 표준 HTTP 상태 코드에 해당합니다. 애플리케이션 로직에서 code 필드를 사용하여 오류를 프로그래매틱 방식으로 처리합니다.

생성 차단 코드

이러한 오류 코드는 정책, 안전 또는 콘텐츠 제한으로 인해 모델의 출력이 차단되었음을 나타냅니다. 이러한 코드 중 하나를 수신하면 입력을 수정하고 다시 시도합니다.

생성 오류 코드

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

오류 응답 형식

Interactions API의 모든 오류는 error가 포함된 code 및 message 객체를 반환합니다. 예를 들어 지원되지 않는 도구 유형을 전달하면 다음이 반환됩니다.

{
  "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는 서버 전송 이벤트(SSE) 스트림을 통해 event_type이(가) "error"로 설정된 오류 이벤트를 전송합니다. error 필드에는 동일한 code 및 message 구조가 포함되어 있습니다.

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

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

다음 단계

• API 문제 해결: 일반적인 문제 및 오류 시나리오를 해결합니다.
• 속도 제한: 요청 한도 및 할당량 처리에 대해 알아봅니다.