오류와 복구

일반적인 HTTP 오류와 SDK 예외는 공통 오류 코드 가이드를 참고하세요.

오류 확인

요청 오류가 발생하면 HTTP 응답을 확인하세요. 턴을 실행하거나 환경을 설정하는 중에 오류가 발생하면 이벤트와 저장된 상태를 확인하세요.

구조화된 오류를 처리할 때는 애플리케이션 로직에서 error.code를 사용하고, 실패 이유를 설명할 때는 error.message를 사용하세요. 요청 유효성 검사 오류의 경우 error.param으로 수정할 필드를 파악할 수 있습니다. 알 수 없는 코드가 들어오거나 param이 없어도 오류 처리기가 정상적으로 동작하도록 하세요.

베타 API(OpenAI-Beta: agents=v1)에서 세션의 error 값은 메시지 문자열 또는 null입니다. 세션 실패 코드는 함께 전송되는 SSE error 이벤트에서 확인하세요.

API 요청 오류

이 오류는 Agents API에 보낸 요청에서 발생합니다. 작업을 시작한 후 반환되는 턴 오류와는 구분됩니다.

Files API 요청 한도

세션 생성 또는 파일 첨부 요청에 대해 HTTP 429와 함께 files_api_rate_limit_exceeded가 반환될 수 있습니다. Agents API는 Files API를 통해 파일을 확인합니다. 이때 인증된 사용자의 Files API 요청 할당량이 차감됩니다. 첨부한 파일마다 별도의 확인 요청이 필요할 수 있습니다.

12345678{
  "error": {
    "type": "rate_limit_error",
    "code": "files_api_rate_limit_exceeded",
    "message": "The Files API rate limit for your user has been exceeded. Reduce the rate of requests that access files, then try again.",
    "param": null
  }
}

파일에 접근하는 동시 요청 수를 줄이세요. 재시도할 때는 지수 백오프를 적용하고 최대 시도 횟수를 정하세요. 즉시 재시도하면 할당량이 계속 소진될 수 있습니다.

이 HTTP 응답은 요청한 작업이 실패했다는 뜻입니다. 생성 성공 응답을 받은 뒤 세션이나 턴이 비동기적으로 실패하는 경우와는 다릅니다. 이 오류를 식별하려면 메시지 텍스트를 비교하는 대신 error.code를 확인하세요.

턴 오류

실패한 턴의 상태는 status: "failed"이며, error에는 code와 message가 포함됩니다. 예를 들어 모델에 과부하가 발생하면 다음 오류가 반환될 수 있습니다.

1234{
  "code": "server_overloaded",
  "message": "The model is temporarily overloaded. Please retry your request after a brief delay."
}

턴 오류 코드에는 별도의 HTTP 상태 코드가 없습니다. 예를 들어 실패한 턴에서는 server_overloaded를 사용하고, HTTP 응답에서는 server_is_overloaded를 사용할 수 있습니다.

세션 및 환경 오류

턴이 실패했다고 해서 세션도 반드시 실패한 것은 아닙니다. 세션을 조회해 작업을 이어갈 수 있는지 확인하세요. status 값이 requires_action이면 필요한 조치를 처리하세요. 세션이 실패했다면 원인을 해결한 후 여전히 필요한 입력으로 새 세션을 생성하세요.

복구

일시적인 오류 발생 시 재시도

요청 한도 초과, 과부하, 시간 초과, 일시적인 서비스 장애가 발생하면 다음 절차를 따르세요. 잘못된 입력, 자격 증명 문제, 결제 한도 문제는 재시도하기 전에 해결하세요.

1. 작업 결과를 확인하세요. 세션이 생성되었다면 해당 세션과 턴, 저장된 항목을 조회하세요. 턴이 아직 진행 중이면 계속 상태를 확인하세요. 완료되었다면 해당 결과를 사용하세요.
2. 이미 실행된 작업을 확인하세요. 턴이 실패했더라도 파일을 이미 변경했거나 외부 도구를 호출했을 수 있습니다. 에이전트에 작업을 다시 요청하기 전에 해당 작업이 미친 영향을 확인하세요.
3. 잠시 기다리고 재시도를 제한하세요. 공통 재시도 안내에 따라 HTTP 응답의 Retry-After에 지정된 시간을 지키고 최대 시도 횟수나 마감 시간을 설정하세요.
4. 요청을 재시도하거나 새 턴을 시작하세요. HTTP 오류가 발생했다면 원래 작업의 결과를 확인한 후 해당 작업을 재시도하세요. 턴이 실패했다면 세션이 idle 상태가 될 때까지 기다린 후 후속 메시지를 보내 완료되지 않은 작업만 이어서 수행하도록 요청하세요. 그러면 기존 대화에서 새 턴이 시작됩니다.

턴이 완료되었더라도 도구 실행 결과를 확인하세요. 오류가 달라지거나 재시도 한도에 도달하면 자동 재시도를 중단하세요.

잘못된 입력 수정

다시 제출하기 전에 error.param 또는 error.message가 가리키는 필드를 수정하세요.

크기 관련 오류가 발생했다면 재시도하기 전에 입력 및 출력 스키마 또는 도구 실행 결과의 크기를 줄이세요. 에이전트 설정이 너무 크면 지침과 도구 정의의 크기를 줄여 새 세션을 생성하세요.

업로드 요구 사항과 예시는 업로드 오류 해결을 참고하세요. 메시지에 이미지 문제가 표시되면 이미지 데이터나 URL을 확인하세요.

스트림 연결 끊김

error 이벤트나 스트림 연결 끊김만으로는 턴의 최종 상태를 알 수 없습니다. 입력을 다시 제출하기 전에 끊어진 스트림 복구 절차에 따라 다시 연결하고 저장된 작업을 확인하세요. 조회한 세션의 상태가 status: "failed"이거나 agent.session.failed 이벤트를 받으면 재연결을 중단하고 세션 복구 안내를 따르세요.

오류가 지속되어 지원팀에 문의할 때는 요청 ID, 세션 ID, 턴 ID를 함께 보내세요.