OperasyonEntegrasyon Önizlemesi

Hata Yönetimi

Hata yanıtlarının yapısı, hata kodları ve güvenli yeniden deneme stratejileri.

Önizleme

Hata kodları ve yanıt yapısı örnek amaçlıdır. Rate limit değerleri bu dokümanda taahhüt edilmez; hesabınıza özel limitler entegrasyon dokümanında paylaşılır.

ReinoAds, standart HTTP durum kodlarını kullanır ve her hata yanıtında makine tarafından okunabilir bir code alanı döndürür. Bir reklam kararının blocked_by_policy veya no_fill olması bir hata değildir; bunlar 200 yanıtı içinde outcome olarak döner.

{
  "error": {
    "code": "invalid_placement",
    "message": "Placement 'rewarded_v2' was not found in this environment.",
    "param": "placement",
    "request_id": "req_01HZXD8W2K"
  }
}

code	HTTP	Anlamı
invalid_request	400	İstek gövdesi geçersiz veya zorunlu alan eksik.
missing_consent	400	consent nesnesi gönderilmedi.
authentication_failed	401	API anahtarı eksik, geçersiz veya iptal edilmiş.
permission_denied	403	Anahtar bu işlem için yetkili değil; örn. publishable key ile yönetim endpoint'i çağrıldı.
environment_mismatch	403	Sandbox anahtarıyla live kaynağına erişilmeye çalışıldı veya tersi.
invalid_placement	404	Yerleşim bu ortamda bulunamadı.
conflict	409	Aynı adla kaynak zaten var veya eşzamanlı güncelleme çakıştı.
rate_limited	429	Kısa sürede çok fazla istek gönderildi.
internal_error	500	ReinoAds tarafında beklenmeyen hata.
service_unavailable	503	Servis geçici olarak kullanılamıyor.

Yeniden deneme

4xx hatalarını (429 hariç) yeniden denemeyin; isteği düzeltin.
429, 500 ve 503 için üstel geri çekilme ve rastgele gecikme (jitter) ile yeniden deneyin; Retry-After başlığı varsa ona uyun.
Yönetim endpoint'lerine yapılan POST isteklerinde Idempotency-Key başlığı kullanarak çift kayıt oluşmasını önleyin.
Karar isteklerinde zaman aşımı veya hata durumunda reklam alanını boş bırakın; kullanıcı deneyimini reklam yanıtına bağımlı kılmayın.

async function requestWithRetry(body: unknown, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch("https://api.reinoads.com/v1/decisions", {
      method: "POST",
      headers: {
        Authorization: "Bearer " + process.env.REINOADS_SECRET_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(body)
    });

    if (res.ok) return res.json();
    if (![429, 500, 503].includes(res.status)) throw await res.json();

    const retryAfter = Number(res.headers.get("Retry-After"));
    const delay = retryAfter > 0
      ? retryAfter * 1000
      : 2 ** i * 250 + Math.random() * 100;
    await new Promise((r) => setTimeout(r, delay));
  }
  return { outcome: "no_fill" };
}

Destek talepleri

Destek ekibine başvururken hata yanıtındaki request_id değerini ve varsa karar kimliğini (dec_...) paylaşın. Bu değerler kişisel veri içermez.