Hata Yönetimi

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:

{
  "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

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:

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ı:

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:.

Gönderileri Idempotency-Key ile güvenle yeniden deneyin

POST /twitter/tweets/create ve POST /twitter/tweets/quote, isteğe bağlı bir Idempotency-Key header’ı kabul eder. Her gönderi için yeni bir değer (örneğin UUID) kullanın; zaman aşımı veya ağ hatasından sonra aynı gönderiyi yeniden denerken aynı değeri tekrar gönderin:

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"}'

Anahtarlar 1 ile 255 arası görünür ASCII karakterden oluşur ve API anahtarınıza özeldir. Header olmadan her istek gönderi yapar. MCP twexapi_write çağrıları anahtarı otomatik gönderir: aynı çağrıyı 10 dakika içinde birebir tekrarlamak ilk sonucu döndürür.

MCP hataları

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

MCP kimlik doğrulaması başarısız olduğunda hiçbir araç çalışmaz:

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

MCP istemcisinden tekrar oturum açın veya x-api-key ya da Authorization: Bearer değerini düzeltin, ardından aracı yeniden çağırın. Tüm kimlik doğrulama mesajları için MCP araçları referansına bakın.

Kredi kalmadı

Hesabın kredisi bittiğinde MCP bağlantısı çalışmaya devam eder ve explore ücretsizdir; ancak diğer araç çağrıları API’yi çağırmadan bir hata sonucu döndürür:

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

Durun ve kullanıcıdan bakiye yüklemesini isteyin; yeniden denemek işe yaramaz.

twexapi_request veya twexapi_write üzerinden dönen API hatası

Alttaki REST çağrısı başarısız olduğunda araç sonucunu olduğu gibi saklayın:

{
  "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": []
  }
}

Yukarıdaki HTTP kurtarma tablosunu uygulayın. Modelin yeni bir yol tahmin etmesine izin vermeyin; rota değişmiş olabilirse explore aracını yeniden ç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:

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 bakın.

Yeniden deneme geri çekilme şablonu

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

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 ile eşleştirin; böylece zamanlanmış işler 429 sonrası hemen tam QPS ile yeniden başlamaz.

Çerçeveye özel notlar

İlgili sayfalar

• Hata referansı — uç noktaya göre mesajlar, X hata kodları ve yeniden deneme koşulları
• Rate Limits
• Authentication
• API Overview
• MCP Tools