Hata kodları

Hatalı istekler tutarlı bir gövde döner. code alanı makine tarafından okunmak için, message alanı geliştiriciye göstermek içindir — message metnine göre dallanma yazmayın, o metin uyarı vermeden değişebilir.

{
  "error": {
    "code": "invalid_parameter",
    "message": "limit değeri 1 ile 100 arasında olmalıdır.",
    "param": "limit",
    "request_id": "req_9Xk4Ld"
  }
}

Destek talebi açarken request_id değerini iletin; günlükte doğrudan o isteği buluruz.

Durum kodları

Kod	Anlamı	Ne yapmalı
400	İstek biçimi bozuk	Gövdenin geçerli JSON olduğunu doğrulayın
401	Belirteç yok, süresi dolmuş veya iptal edilmiş	Belirteci yenileyin
403	Belirteç geçerli ama kapsam yetersiz	Anahtara gereken kapsamı ekleyin
404	Kayıt yok veya bu çalışma alanına ait değil	Kimliği ve çalışma alanını doğrulayın
409	Çakışma — kayıt zaten var	Var olan kaydı güncelleyin
422	Biçim doğru, değer geçersiz	param alanına bakın
429	Hız sınırı aşıldı	Retry-After kadar bekleyin
5xx	Bizim tarafımızda hata	Artan aralıkla yeniden deneyin

Sık görülen hata kodları

• invalid_key — Anahtar iptal edilmiş ya da başka bir çalışma alanına ait.
• insufficient_scope — Uç noktanın gerektirdiği kapsam anahtarda yok.
• invalid_parameter — Bir alanın değeri kabul edilen aralığın dışında.
• resource_conflict — Aynı e-postayla ikinci kullanıcı oluşturulmaya çalışıldı.
• rate_limited — Dakikalık istek bütçesi tükendi.

Yeniden denemeyi doğru kurun

Yalnızca 429 ve 5xx yanıtlarını yeniden deneyin; 4xx yanıtları aynı istekle tekrar denemek aynı sonucu verir.

async function callWithRetry(fn, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    const res = await fn();
    if (res.status !== 429 && res.status < 500) return res;

    // 429 ise sunucunun söylediği süreyi bekle, değilse üstel geri çekil
    const retryAfter = Number(res.headers.get('Retry-After'));
    const waitMs = retryAfter ? retryAfter * 1000 : 2 ** i * 500;
    await new Promise((r) => setTimeout(r, waitMs));
  }
  throw new Error('Atlas: yeniden deneme hakkı tükendi');
}

Yazma isteklerinde Idempotency-Key başlığı gönderin. Aynı anahtarla gelen ikinci istek yeni kayıt oluşturmaz, ilk isteğin yanıtını döner — bu sayede yeniden deneme güvenli olur.