속도 제한

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

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

처리량 기대치

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

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

한도 도달 시

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

일반 응답 형태:

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

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

복구 체크리스트

백오프 예제

선택적 Retry-After가 있는 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 참고.

429를 피하는 설계 패턴

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

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

읽기·쓰기 일정 분리

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

안정 조회 캐시

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

MCP explore 절약 사용

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

No-code 및 에이전트 플랫폼

플랫폼 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
• Authentication
• API Overview
• Agent MCP Handoff