---
title: "속도 제한"
description: "TwexAPI 처리량 제한, 429 처리, Retry-After 동작, 프로덕션 작업용 페이지네이션 안전 백오프."
---

TwexAPI는 계정 안정성과 업스트림 X/Twitter fetch 용량을 보호하기 위해 속도 제한을 적용합니다. 실패마다 최대 속도로 재시도하지 말고 내보내기, 에이전트 루프, 예약 작업을 제한에 맞게 설계하세요.

## 처리량 기대치

TwexAPI는 프로덕션 워크로드를 위해 설계되었습니다. 마케팅 벤치마크는 정상 조건에서 클라이언트당 **초당 100요청**까지를 언급하지만, 실제 한도는 엔드포인트 유형, 계정 등급, 플랫폼 부하에 따라 달라집니다.

공개 처리량을 모든 통합의 목표가 아닌 상한으로 취급하세요.

| 워크로드 | 가이드 |
| --- | --- |
| 대화형 에이전트 | 작업당 `explore` 한 번, 관련 `twexapi_request` 일괄 호출. |
| 팔로워 내보내기 | cursor로 페이지네이션; 대형 계정은 페이지 간 지연 추가. |
| 예약 작업 | 시작 시간 분산; `:00`에 모든 워크플로 동시 시작 방지. |
| 쓰기 작업 | 읽기보다 쓰기 볼륨 낮게; 에이전트에서 사람 승인 필수. |

## 한도 도달 시

초과 시 HTTP **`429 Too Many Requests`**가 반환됩니다. 일부 응답에는 **`Retry-After`** 헤더(재시도까지 초)가 있습니다. 있으면 최소 그만큼 기다린 뒤 다음 호출하세요.

일반 응답 형태:

```json
{
  "detail": "Rate limit exceeded. Try again later."
}
```

MCP에서 `twexapi_request`는 도구 결과 안에 동일 상태를 표시합니다. 백오프 전 cursor와 완료된 행을 보존하세요.

## 복구 체크리스트

1. **버스트 트래픽 중지**

    짧은 시간에 많은 요청을 보낸 루프, Prefect flow, n8n 배치, 에이전트 도구 체인을 일시 중지합니다.

2. **Retry-After 확인**

    헤더 값만큼 sleep. 없으면 5–15초부터 시작하고 반복 `429`마다 증가합니다.

3. **마지막 cursor에서 재개**

    **동일 페이지**를 재시도해 행 누락·중복을 방지합니다.

4. **정상 QPS 낮추기**

    작업 재시작 전 요청 간 지연 추가 또는 워커 동시성 감소.

## 백오프 예제

선택적 `Retry-After`가 있는 Python:

```python
import time
import requests

def call_with_backoff(fn, max_attempts=5):
    delays = [5, 15, 45, 120, 300]
    for attempt in range(max_attempts):
        response = fn()
        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        wait = int(retry_after) if retry_after and retry_after.isdigit() else delays[min(attempt, len(delays) - 1)]
        time.sleep(wait)

    return response
```

Prefect 사용자는 `retry_delay_seconds`로 동일 지연을 적용할 수 있습니다 — [Prefect guide](/guides/prefect) 참고.

## 429를 피하는 설계 패턴

### 동일 읽기 병렬화 대신 페이지네이션

페이지 1을 20번 병렬로 가져와도 단일 내보내기가 빨라지지 않습니다. 명시적 샤드를 지원하지 않는 한 cursor를 순차적으로 진행하세요.

### 읽기·쓰기 일정 분리

쓰기는 읽기보다 실질적으로 더 엄격한 한도가 있습니다. 검색·프로필 조회보다 느린 큐에서 게시, 좋아요, 팔로우를 실행하세요.

### 안정 조회 캐시

`user_id`, 프로필 필드, 트윗 메타데이터를 하류 단계에서 재사용할 때 저장하세요. 중복 조회가 줄면 과금 요청도 줄어듭니다.

### MCP `explore` 절약 사용

탐색 호출도 사용량에 포함됩니다. 작업 기간 동안 선택한 `method`와 `path`를 캐시하세요.

## No-code 및 에이전트 플랫폼

| Platform | 패턴 |
| --- | --- |
| [n8n](/guides/n8n) | `429` 후 Wait 노드 추가; cursor를 워크플로 static data에 저장. |
| [Zapier](/guides/zapier) | 지연 내장 replay; 반복 실패 시 ops 알림. |
| [Make](/guides/make) | `429`를 sleep 모듈로 라우팅 후 HTTP 모듈 재시도. |
| [Pipedream](/guides/pipedream) | 대형 내보내기 분할; 워크플로당 동시 단계 상한. |

플랫폼 **webhook**(Catch Hook, Custom Webhook)은 에이전트 핸드오프를 받습니다 — TwexAPI 네이티브 이벤트 스트림이 아닙니다. webhook 수신 후 백오프와 함께 REST 후속 호출을 예약하세요.

## MCP vs REST

두 경로는 동일 계정 한도와 크레dit 모델을 공유합니다. 지연 없이 `twexapi_request`를 루프하는 에이전트는 촘촘한 SDK 루프만큼 빠르게 `429`를 유발할 수 있습니다.

장시간 프로덕션 내보내기에는 자율 에이전트 루프보다 명시적 재시도 정책의 직접 REST 또는 SDK를 선호하세요.

## 속도 제한 상태 모니터링

요청마다 다음 필드를 로깅하세요:

- HTTP status
- Endpoint path
- Cursor 또는 page index
- Retry attempt number
- `Retry-After`(있을 때)

단일 API 키 또는 워크플로에서 `429` 비율이 임계값을 넘으면 알림하세요.

## 관련 페이지

- [Error Handling](/guides/error-handling)
- [Authentication](/authentication)
- [API Overview](/api-reference/overview)
- [Agent MCP Handoff](/mcp/agent-handoff)