---
title: "오류 처리"
description: "TwexAPI HTTP 오류, MCP 도구 실패, 크레dit 한도, 쓰기 작업 재시도 복구."
---

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

## REST 응답 래퍼

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

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

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

## HTTP 상태별 복구

| Status | 의미 | 조치 |
| --- | --- | --- |
| `400` | 잘못된 쿼리, 누락 필드, 잘못된 본문 | 입력 수정. **변경 없이** 재시도하지 마세요. |
| `401` | API 키 누락 또는 무효 | [대시보드](https://twexapi.io/dashboard)에서 자격 증명 교체. `Authorization: Bearer` 형식 확인. |
| `403` | 크레dit 소진, 계정 제한, 작업 불가 | [Get Balance](/api-reference/balance-endpoints/get-balance-api-balance-get) 확인. 충전하거나 접근이 복구될 때까지 쓰기 단계 제거. |
| `404` | 트윗, 사용자, 리스트, 리소스 없음 | ID, screen name, cursor 신선도 확인. |
| `422` | 구조화 입력 검증 실패 | 엔드포인트 페이지의 스키마 필드 수정. 변경 없이 재시도하지 마세요. |
| `429` | 속도 제한 초과 | [Rate Limits](/guides/rate-limits)로 백오프. `next_cursor`와 완료된 행 보존. |
| `5xx` | 일시적 서비스 또는 업스트림 fetch 실패 | 지수 백오프와 상한으로 재시도. |

## 크레dit 및 잔액

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

```bash
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`

복구 규칙:

| 상황 | 조치 |
| --- | --- |
| 쓰기에서 `401` | 재시도 전 API 키와 cookie 자격 증명 수정. |
| 쓰기에서 `403` | 크레dit 및 연결 계정 권한 확인. |
| 모호한 성공 | 중복 작업 전 읽기 엔드포인트로 트윗, DM, 참여 상태 조회. |
| 에이전트 워크플로 | `read_only: false` MCP 호출 전 사람 승인 필수. |

Public docs focus on API-key reads.

## MCP 오류

### 도구 실행 전 인증 실패

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

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

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

### `twexapi_request`를 통한 API 오류

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

```json
{
  "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 예제:

```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 페이지](/sdks) 참고.

## 재시도 백오프 템플릿

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

```python
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](/guides/rate-limits)와 함께 사용하세요.

## 프레임워크별 참고

| Runtime | 가이드 |
| --- | --- |
| [LangChain](/guides/langchain) | 핸드오프 모델 검증; `401`에서 그래프 중지. |
| [Prefect](/guides/prefect) | 지터가 있는 작업 재시도; cursor를 작업 상태에 저장. |
| [n8n / Zapier / Make](/guides/no-code-workflow-handoff) | `401`/`403`을 ops 알림으로; `429` 재생은 지연. |
| [MCP agents](/mcp/agent-handoff) | 부분 성공 후 `next_cursor`를 버리지 마세요. |

## 관련 페이지

- [Rate Limits](/guides/rate-limits)
- [Authentication](/authentication)
- [API Overview](/api-reference/overview)
- [MCP Tools](/mcp/tools)