오류 처리

TwexAPI HTTP 오류, MCP 도구 실패, 크레dit 한도, 쓰기 작업 재시도 복구.

TwexAPI 오류는 두 계층에서 반환됩니다: MCP JSON-RPC 오류(도구 실행 전 인증)와 REST HTTP 오류(요청이 API에 도달한 후). 재시도와 사람 검토를 안전하게 하려면 상태 코드, 응답 본문, cursor, ID를 보존하세요.

REST 응답 래퍼

성공 호출은 다음을 반환합니다:

{
  "code": 200,
  "msg": "success",
  "data": {}
}

HTTP 상태가 2xx가 아니면 본문에 code 필드가 있어도 실패로 처리합니다. 전체 본문, 요청 경로, 이미 소비한 cursor를 로깅하세요.

HTTP 상태별 복구

크레dit 및 잔액

과금 읽기·쓰기는 계정 크레dit을 소비합니다. 많은 페이지를 처리하는 작업은 장시간 실행 전후에 잔액을 확인하세요:

curl --request GET \
  --url 'https://api.twexapi.io/balance' \
  --header 'Authorization: Bearer YOUR_API_KEY'

403 응답에 크레dit 또는 접근 관련 내용이 있으면:

1. API를 계속 호출하는 예약 작업 중지.
2. 대시보드에서 잔액 확인.
3. 크레dit 복구 후 마지막 저장 cursor부터 재개.

페이지네이션 안전 재시도

검색, 팔로워, 타임라인, DM 기록의 경우:

• next_cursor, has_next_page, task_id를 에이전트 대화 밖에 저장.
• 429 또는 5xx 후 동일 cursor로 재시도, 다음 페이지 아님.
• 400, 404, 422 후 ID와 쿼리 매개변수를 검사한 뒤 재시도.

쓰기 작업

쓰기 엔드포인트(트윗, 답글, 좋아요, 팔로우, DM 발송)에는 다음이 필요합니다:

• 유효한 TwexAPI API 키
• 요청에 저장된 Twitter cookie 또는 auth_token

복구 규칙:

Public docs focus on API-key reads.

MCP 오류

도구 실행 전 인증 실패

MCP 인증이 실패하면 explore와 twexapi_request는 실행되지 않습니다:

{
  "jsonrpc": "2.0",
  "error": {
    "code": 401,
    "message": "Missing MCP API token"
  }
}

MCP 클라이언트의 x-api-key 또는 Authorization: Bearer를 수정한 뒤 도구 호출을 다시 실행하세요.

twexapi_request를 통한 API 오류

기본 REST 호출이 실패하면 도구 결과를 보존합니다:

{
  "status_code": 403,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "detail": "Credits exhausted or action not allowed."
  }
}

위 HTTP 복구 표와 동일하게 적용합니다. 경로가 바뀌었을 수 있으면 새 경로를 추측하지 말고 explore를 다시 호출하세요.

SDK 및 CLI 오류

생성된 SDK는 HTTP 실패를 언어별 예외로 매핑합니다. 작업 경계에서 오류를 잡고 상태 코드와 응답 본문을 로깅하며 429/5xx는 재시도 정책으로 라우팅하세요.

Python 예제:

import requests

try:
    response = requests.get(
        "https://api.twexapi.io/balance",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        timeout=30,
    )
    response.raise_for_status()
except requests.HTTPError as exc:
    status = exc.response.status_code
    body = exc.response.text
    if status == 429:
        # Back off, preserve cursor, retry later
        ...
    elif status in (400, 404, 422):
        # Fix input; do not retry unchanged
        ...
    raise

언어별 패턴은 각 SDK 페이지 참고.

재시도 백오프 템플릿

429와 5xx에 상한 지수 백오프 사용:

retry_delays_seconds = [5, 15, 45, 120]

for delay in retry_delays_seconds:
    response = call_twexapi()
    if response.ok:
        break
    if response.status_code in (429, 500, 502, 503, 504):
        time.sleep(delay)
        continue
    break  # 4xx other than 429: stop and fix input

429 직후 예약 작업이 전체 QPS로 재시작하지 않도록 Rate Limits와 함께 사용하세요.

프레임워크별 참고

관련 페이지

• Rate Limits
• Authentication
• API Overview
• MCP Tools