오류 처리

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.

Idempotency-Key로 게시를 안전하게 재시도하기

POST /twitter/tweets/create와 POST /twitter/tweets/quote는 선택적인 Idempotency-Key 헤더를 받습니다. 게시마다 새 값(예: UUID)을 사용하고, 타임아웃이나 네트워크 오류 후 같은 게시를 재시도할 때는 같은 값을 다시 보내세요.

curl https://api.twexapi.io/twitter/tweets/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-467f-a8d1-1f0b4c2a9e01" \
  -d '{"cookie": "auth_token=...; ct0=...", "tweet_content": "Hello from TwexAPI"}'

키는 1~255자의 표시 가능한 ASCII 문자이며 API 키별로 구분됩니다. 헤더가 없으면 요청할 때마다 게시됩니다. MCP twexapi_write 호출은 키를 자동으로 보내므로, 10분 안에 완전히 같은 호출을 반복하면 첫 번째 결과가 반환됩니다.

MCP 오류

도구 실행 전 인증 실패

MCP 인증에 실패하면 어떤 도구도 실행되지 않습니다.

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Access token is invalid or expired"
  }
}

MCP 클라이언트에서 다시 로그인하거나 x-api-key 또는 Authorization: Bearer를 수정한 뒤 도구를 다시 호출하세요. 모든 인증 오류 메시지는 MCP 도구 레퍼런스에 있습니다.

크레딧 소진

계정의 크레딧이 소진되어도 MCP 연결은 유지되고 explore는 무료로 사용할 수 있습니다. 다만 다른 도구 호출은 API를 호출하지 않고 오류 결과를 반환합니다.

{
  "error": "No credits left on this TwexAPI account. Top up at https://twexapi.io/dashboard and try again."
}

작업을 멈추고 사용자에게 충전을 안내하세요. 재시도해도 해결되지 않습니다.

twexapi_request 또는 twexapi_write로 반환된 API 오류

하위 REST 호출이 실패하면 도구 결과를 그대로 보존하세요.

{
  "status_code": 429,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "code": 429,
    "msg": "Rate limit exceeded. QPS limit: 2 requests per second",
    "data": []
  }
}

위의 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와 함께 사용하세요.

프레임워크별 참고

관련 페이지

• 오류 참조 — 엔드포인트별 메시지, X 오류 코드 및 재시도 조건
• Rate Limits
• Authentication
• API Overview
• MCP Tools