오류와 재시도

오류 응답 형식

오류는 항상 아래 envelope로 옵니다.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request limit exceeded",
    "retryable": true,
    "request_id": "0b7b8f0e-0000-4000-8000-000000000010",
    "details": {"reset_at": "2026-10-05T09:01:00+00:00"}
  }
}

• 모든 응답에 X-Request-Id 헤더가 있고 본문의 request_id와 같습니다. 서버가 요청마다 새로 발급합니다.
• 429와 일부 503에는 Retry-After(초) 헤더가 있습니다.
• 모든 응답은 Cache-Control: no-store입니다.
• 요청에 X-Correlation-Id를 넣으면 호출자 쪽 추적에 쓸 수 있습니다. 서버가 만드는 request_id와는 별개입니다.
• 접수에 성공(202)한 Turn이나 Run이 나중에 실패하는 것은 HTTP 오류가 아닙니다. 상세 조회 응답의 error.code로 확인합니다.

재시도 원칙

1. retryable이 true인 오류와 네트워크 오류(연결 끊김, 시간 초과)만 재시도합니다.
2. Retry-After가 있으면 그 시간만큼 기다립니다. 없으면 지수 백오프에 무작위 지연을 더합니다.
3. 생성, 입력, 취소, 업로드 요청은 재시도할 때 같은 Idempotency-Key와 같은 본문을 보냅니다. 이미 접수된 요청이면 같은 receipt가 돌아오므로 중복 실행이 없습니다.
4. retryable이 false인 오류는 같은 요청을 그대로 다시 보내도 같은 결과입니다. 요청을 고치거나 원인을 해결하세요.
5. 응답을 못 받은 요청을 새 키로 다시 보내면 같은 일이 두 번 실행될 수 있습니다. 재시도에는 키를 바꾸지 마세요.
6. 재시도 횟수와 총 대기 시간에 상한을 두세요.

def post_with_retry(url: str, key: str, body: dict, attempts: int = 5) -> httpx.Response:
    for attempt in range(attempts):
        try:
            response = httpx.post(url, headers={**AUTH, "Idempotency-Key": key}, json=body, timeout=30)
        except httpx.TransportError:
            response = None
        if response is not None and response.status_code < 400:
            return response
        try:
            error = response.json().get("error", {}) if response is not None else {}
        except ValueError:  # a proxy may answer 502/503/504 without the JSON envelope
            error = {"retryable": response.status_code in (429, 502, 503, 504)}
        if response is not None and not error.get("retryable"):
            response.raise_for_status()
        delay = float(response.headers.get("Retry-After", 0)) if response is not None else 0
        time.sleep(delay or min(30, 0.5 * 2 ** attempt))
    raise RuntimeError("gave up after retries")

HTTP 상태별 의미

오류 코드 표

아래 표는 호출자가 받을 수 있는 공개 코드입니다. HTTP 상태가 -인 코드는 HTTP 응답이 아니라 Turn이나 Run 상세의 error.code로만 보이며, 이때 retryable은 false입니다. retryable은 같은 요청을 다시 보내는 것에 대한 값이라 끝난 실행에서는 늘 false입니다. 새 실행을 만들어도 되는지는 아래 “실패한 실행 뒤 다음 행동” 표를 따르세요. SESSION_SANDBOX_UNAVAILABLE처럼 HTTP 응답과 실행 상세에 모두 쓰이는 코드는 한 행에 HTTP 응답일 때의 상태와 retryable을 적고, 실행 상세에서 보일 때의 뜻을 의미 칸에 함께 적었습니다. 내부에서만 쓰는 코드는 싣지 않았습니다. 새 코드가 추가될 수 있으니 모르는 코드는 retryable과 HTTP 상태로 처리하세요.

실패한 실행 뒤 다음 행동

Turn이나 Run이 FAILED, CANCELED, EXPIRED로 끝나면 그 실행은 다시 살아나지 않습니다. 다시 하려면 새 Idempotency-Key로 새 Turn이나 Run을 만듭니다. 응답을 받지 못한 요청을 같은 키로 다시 보내는 위의 재시도와는 다릅니다. 끝난 실행의 키를 그대로 쓰면 끝난 실행의 receipt가 다시 돌아옵니다.

AI 도구가 호출을 대신하는 경우에도 아래 순서를 지키세요. 새 실행은 비용이 다시 듭니다.

표에 없는 코드는 다시 실행하지 말고 멈춘 뒤 사람에게 알리세요.

실행 중 AI 직원이 낸 결과가 공개 결과 규칙에 걸리면 그 실행은 그 자리에서 실패로 끝납니다. 결과 형식 오류 가운데 JSON 결과의 schema 불일치만 실행 중 AI 직원에게 돌려줘 고치게 합니다. 실패하지 않고 일부 결과만 받는 워크플로(PARTIALLY_SUCCEEDED)에서는 실패한 결과 항목의 error.code에 같은 코드가 남습니다.

조직 업무 준비의 실패도 HTTP 오류가 아닙니다. 사유는 준비의 reason_codes에 있고, 다음 행동은 조직 업무 만들기에 있습니다.