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'."
  }
}

오류가 전송되는 방식

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

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

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

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

다음 단계

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