Hatalar

Tüm API anahtarı uç noktaları JSON formatında yanıt verir. 2xx serisi dışındaki tüm yanıtlarda, yanıt gövdesi aynı yapıya sahiptir:

{
  "success": false,
  "error": "<human-readable message>"
}

Bazı hatalarda fazladan bağlam yer alır (ör. krediler (429 kota hatası nedeniyle). HTTP durum kodu en güvenilir kaynaktır — duruma göre dallanma yapın, ardından okuyun hata görüntüleme veya kayıt amacıyla.

Durum kodu referansı#

İkisini birbirinden ayırmak 429 durumlar#

A 429 her zaman "şimdilik göndermeyi durdur" anlamına gelir, ancak neden önemlidir.

İstek sınırı (kullanıcı başına dakikada 60):

{
  "success": false,
  "error": "Rate limit exceeded. Max 60 requests per minute."
}

Aylık kredi limiti (20.000 / ay, kullanıcı başına):

{
  "success": false,
  "error": "Monthly credit limit reached (20000). Resets next month.",
  "credits": { "used": 20000, "limit": 20000, "remaining": 0 }
}

Şube, şunun varlığına bağlı olarak krediler nesnesi üzerinde ya da "Aylık kredi limiti". Bkz. Hız sınırları ve Krediler ve faturalandırma her bir durum için kurtarma stratejisi.

Hata işleme modeli (Node.js)#

async function whFetch(path, init = {}) {
  const res = await fetch(`${ORIGIN}${path}`, {
    ...init,
    headers: { 'X-API-Key': process.env.WH_API_KEY, ...(init.headers || {}) },
  });

  let body = null;
  try { body = await res.json(); } catch { /* non-JSON, leave null */ }

  if (res.ok) return body;

  const error = (body && body.error) || res.statusText;

  if (res.status === 401) throw new Error(`Auth failed: ${error}`);
  if (res.status === 403) throw new Error(`Plan required: ${error}`);
  if (res.status === 404) throw new Error(`Unknown endpoint: ${path}`);
  if (res.status === 429) {
    const retryable = body && body.credits ? false : true; // monthly quota is not retryable today
    const err = new Error(error);
    err.retryable = retryable;
    throw err;
  }
  if (res.status >= 500) {
    const err = new Error(`Upstream error: ${error}`);
    err.retryable = true;
    throw err;
  }
  throw new Error(`HTTP ${res.status}: ${error}`);
}

Hata işleme modeli (Python)#

import os, requests

def wh_fetch(path, **kwargs):
    r = requests.request(
        method=kwargs.pop("method", "GET"),
        url=f"{ORIGIN}{path}",
        headers={"X-API-Key": os.environ["WH_API_KEY"], **kwargs.pop("headers", {})},
        **kwargs,
    )

    body = None
    try:
        body = r.json()
    except ValueError:
        pass

    if r.ok:
        return body

    error = (body or {}).get("error") or r.reason

    if r.status_code == 401:
        raise PermissionError(f"Auth failed: {error}")
    if r.status_code == 403:
        raise PermissionError(f"Plan required: {error}")
    if r.status_code == 429:
        is_quota = bool((body or {}).get("credits"))
        raise RuntimeError(f"Rate limited (quota={is_quota}): {error}")
    if r.status_code >= 500:
        raise RuntimeError(f"Upstream error: {error}")

    raise RuntimeError(f"HTTP {r.status_code}: {error}")

Yanıt biçimi ve HTTP durumu#

• API anahtarı koruma hataları (kullanım sınırına ulaşma) (401, 403, sınır 429, genel hat 500) her zaman şu şekilde JSON döndürür: başarı: false ve buna uygun bir HTTP durumu.
• Bazı JSON işleyicileri (özellikle büyük TikTok Shop veri yükleri) HTTP yanıtı verebilir 200 iş düzeyinde bayraklar içeren bir yapıya sahipse — varsayımda bulunmak yerine her zaman o uç noktanın şemasını okuyun başarı Yalnızca HTTP isteklerini izler.

JSON yerine HTML mi? Ölçümlü programlı rotalar kümesi İçerik Türü: application/json. HTML genellikle yanlış bir sunucu, bir proxy hata sayfası veya uygulamaya hiç ulaşmayan bir yol anlamına gelir — bkz. Sorun Giderme.

Hata bildirme#

Eğer bir 500 ya da belgelerle çelişen bir yanıt:

1. İstek URL'sini, yöntemini, başlıklarını (anahtarınızı gizleyin) ve gövdesini kaydedin.
2. Yanıt durumunu ve gövdesini yakala.
3. Zaman damgasını not edin.
4. Paketi destek ekibine gönderin — ekip, kullanıcı kimliği ve zaman damgası bilgilerini kullanarak sunucu günlükleriyle karşılaştırma yapabilir.