---
title: "Hata Yönetimi"
description: "TwexAPI HTTP hataları, MCP araç hataları, kredi limitleri ve yazma işlemi yeniden denemelerinden kurtulun."
---

TwexAPI hataları iki katmanda döner: **MCP JSON-RPC hataları** (bir araç çalışmadan önce kimlik doğrulama) ve **REST HTTP hataları** (istek API'ye ulaştıktan sonra). Yeniden denemeler ve insan incelemesi güvenli kalsın diye durum kodlarını, yanıt gövdelerini, imleçleri ve ID'leri koruyun.

## REST yanıt zarfı

Başarılı çağrılar şunu döndürür:

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

HTTP durumu `2xx` değilse, gövdede `code` alanı olsa bile yanıtı hata olarak değerlendirin. Tam gövdeyi, istek yolunu ve tüketilmiş imleçleri günlüğe kaydedin.

## HTTP durum kurtarma

| Durum | Anlam | Eylem |
| --- | --- | --- |
| `400` | Geçersiz sorgu, eksik alan veya hatalı gövde | Girdiyi düzeltin. **Değiştirmeden** yeniden denemeyin. |
| `401` | Eksik veya geçersiz API anahtarı | [dashboard](https://twexapi.io/dashboard)'dan kimlik bilgisini değiştirin. `Authorization: Bearer` biçimini kontrol edin. |
| `403` | Kredi tükendi, hesap kısıtlandı veya işleme izin yok | [Get Balance](/api-reference/balance-endpoints/get-balance-api-balance-get) sayfasına bakın. Bakiye yükleyin veya erişim dönene kadar yazma adımlarını kaldırın. |
| `404` | Tweet, kullanıcı, liste veya kaynak bulunamadı | ID'leri, kullanıcı adlarını ve imleç güncelliğini doğrulayın. |
| `422` | Yapılandırılmış girdide doğrulama başarısız | Uç nokta sayfasında belgelenen şema alanlarını düzeltin. Değiştirmeden yeniden denemeyin. |
| `429` | Hız sınırı aşıldı | [Rate Limits](/guides/rate-limits) ile geri çekilin. `next_cursor` ve tamamlanan satırları koruyun. |
| `5xx` | Geçici servis veya üst akış getirme hatası | Üst sınırlı üstel geri çekilme ile yeniden deneyin. |

## Krediler ve bakiye

Ölçülü okuma ve yazmalar hesap kredilerini harcar. Uzun işlerde birçok sayfa işlerken bakiyeyi başta ve sonda kontrol edin:

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

`403` yanıtları kredi veya erişimden bahsediyorsa:

1. API'ye sürekli istek atan zamanlanmış işleri durdurun.
2. Dashboard'da bakiyeyi doğrulayın.
3. Krediler geri geldikten sonra son kaydedilen imleçten devam edin.

## Sayfalama güvenli yeniden denemeler

Arama, takipçiler, zaman çizelgeleri ve DM geçmişi için:

- `next_cursor`, `has_next_page` ve `task_id` değerlerini agent konuşmasının dışında saklayın.
- `429` veya `5xx` sonrası **aynı imleci** yeniden deneyin, sonraki sayfayı değil.
- `400`, `404` veya `422` sonrası yeniden denemeden önce ID'leri ve sorgu parametrelerini inceleyin.

## Yazma işlemleri

Yazma uç noktaları (tweet, yanıt, beğeni, takip, DM gönderme) şunları gerektirir:

- Geçerli bir TwexAPI API anahtarı
- İstekte kayıtlı bir Twitter cookie'si veya `auth_token`

Kurtarma kuralları:

| Durum | Eylem |
| --- | --- |
| Yazmada `401` | Yeniden denemeden önce API anahtarı ve cookie kimlik bilgilerini düzeltin. |
| Yazmada `403` | Kredileri ve bağlı hesabın hâlâ izni olup olmadığını doğrulayın. |
| Belirsiz başarı | Eylemi yinelemeden önce okuma uç noktasıyla tweet, DM veya etkileşim durumuna bakın. |
| Agent iş akışları | `read_only: false` MCP çağrısından önce insan onayı isteyin. |

TwexAPI ayrı bir yazma işlemi yoklama API'si sunmaz. Yinelenen yan etkilerden önce tweet arama, DM durumu gibi idempotent okuma kontrollerini tercih edin. Cookie kurulumu ve `403` kurtarma:.

## MCP hataları

### Araç çalışmadan önce kimlik doğrulama başarısız

MCP kimlik doğrulaması başarısız olursa `explore` ve `twexapi_request` çalışmaz:

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

MCP istemcisinde `x-api-key` veya `Authorization: Bearer` değerini düzeltin, ardından araç çağrısını yeniden çalıştırın.

### `twexapi_request` üzerinden dönen API hatası

Altta yatan REST çağrısı başarısız olursa araç sonucunu koruyun:

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

Yukarıdaki HTTP kurtarma tablosunu uygulayın. Modele yeni yol tahmin ettirmeyin — rota değişmiş olabilirse `explore`'u tekrar çağırın.

## SDK ve CLI hataları

Oluşturulan SDK'lar HTTP hatalarını dile özgü istisnalara eşler. Hataları iş sınırında yakalayın, durum kodunu ve yanıt gövdesini günlüğe kaydedin, `429`/`5xx` için yeniden deneme politikalarına yönlendirin.

Python örneği:

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

Dile özgü desenler için her [SDK sayfasına](/sdks) bakın.

## Yeniden deneme geri çekilme şablonu

`429` ve `5xx` için üst sınırlı üstel geri çekilme kullanın:

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

Geri çekilmeyi [Rate Limits](/guides/rate-limits) ile eşleştirin; böylece zamanlanmış işler `429` sonrası hemen tam QPS ile yeniden başlamaz.

## Çerçeveye özel notlar

| Çalışma zamanı | Rehberlik |
| --- | --- |
| [LangChain](/guides/langchain) | Devir modellerini doğrulayın; `401`'de grafiği durdurun. |
| [Prefect](/guides/prefect) | Jitter'lı görev yeniden denemeleri kullanın; imleçleri görev durumunda saklayın. |
| [n8n / Zapier / Make](/guides/no-code-workflow-handoff) | `401`/`403`'ü operasyon uyarılarına yönlendirin; `429` tekrarlarını geciktirin. |
| [MCP agents](/mcp/agent-handoff) | Kısmi başarıdan sonra `next_cursor`'u asla atmayın. |

## İlgili sayfalar

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