Hata Yönetimi

Hata yanıtı formatı

Bir istek başarısız olduğunda API, bir HTTP hata durum kodu ve success: false içeren bir JSON gövdesiyle yanıt verir. error nesnesi; sayısal bir code, makine tarafından okunabilir bir type ve insan tarafından okunabilir bir info mesajı içerir:

{
  "success": false,
  "error": {
    "code": 101,
    "type": "no_api_key",
    "info": "User did not supply an API Key"
  }
}

Kodunuzda değişebilecek olan info metnine göre değil, code veya type değerine göre dallanın. Kodlar MetalAPI'nin önceki sürümleriyle aynıdır; bu sayede mevcut entegrasyonlar çalışmaya devam eder.

Kimlik doğrulama ve hesap hataları

• 101 no_api_key (401): istekte API anahtarı yok.
• 102 invalid_api_key (401): anahtar bilinmiyor veya iptal edilmiş.
• 103 account_inactive (403): hesap aktif değil. Destek ekibiyle iletişime geçin.
• 107 origin_not_allowed (403): alan adıyla sınırlandırılmış bir anahtar, izin listesinde olmayan bir web sitesinden kullanıldı.

Limit ve plan hataları

• 104 too_many_requests (429): dakika başına limite ulaşıldı. Retry-After header'ında belirtilen saniye kadar bekleyin.
• 105 quota_exceeded (429): aylık kota tükendi ve bir sonraki ayın 1'ine (UTC) kadar kullanılamaz.
• 106 plan_restriction (403): endpoint veya parametre planınıza dahil değil; örneğin Free planda /carat ya da Standard'ın altındaki planlarda XAU-BID.

Doğrulama hataları

Bu hatalar HTTP 400 durum kodu döndürür ve isteğin kendisinin düzeltilmesi gerektiği anlamına gelir:

• 201 invalid_base: bilinmeyen base sembolü.
• 202 invalid_from ve 203 invalid_to: /convert içinde bilinmeyen from veya to sembolü.
• 204 invalid_amount: amount eksik veya bir sayı değil.
• 205 invalid_date: hatalı biçimlendirilmiş tarih ya da gelecekteki bir tarih.
• 206 invalid_timeframe: start_date veya end_date eksik ya da başlangıç tarihi bitiş tarihinden sonra.
• 207 timeframe_too_long: aralık, planınızın izin verdiğinden uzun (Free planda 30 gün, ücretli planlarda 365 gün).
• 208 invalid_symbols: istenen sembollerin hiçbiri mevcut değil.
• 209 invalid_unit: desteklenmeyen unit.
• 210 invalid_carat: desteklenmeyen ayar.

currencies içinde en az bir sembol geçerli olduğu sürece bilinmeyen semboller atlanır.

Diğer hatalar

• 300 no_results (404): sorgu geçerli ancak veri yok; örneğin bir sembolün geçmiş verisinin başladığı tarihten önceki bir tarih.
• 404 invalid_function (404): bilinmeyen endpoint. URL'yi kontrol edin.
• 500 server_error (500): bizim tarafımızda beklenmeyen bir hata.
• 503 service_unavailable (503): fiyat verileri geçici olarak kullanılamıyor.

Hataları kodda ele almak

Her yanıtta success alanını kontrol edin ve başarısızlıkları kodunuzun inceleyebileceği hatalara dönüştürün. Bu yardımcı fonksiyon, proxy'lerden gelen JSON olmayan yanıtları da ele alır:

async function metalapi(path, params = {}) {
  const url = new URL(`https://metalapi.com/api/v1/${path}`);
  for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);

  const res = await fetch(url, { headers: { "X-API-Key": process.env.METALAPI_KEY } });
  const data = await res.json().catch(() => ({
    success: false,
    error: { code: res.status, type: "http_error", info: res.statusText },
  }));

  if (!data.success) {
    const err = new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
    err.code = data.error.code;
    err.retryAfter = Number(res.headers.get("Retry-After")) || undefined;
    throw err;
  }
  return data;
}

Yeniden deneme stratejisi

Yalnızca ikinci denemede başarılı olabilecek hataları yeniden deneyin:

• 104: Retry-After header'ında belirtilen saniye kadar bekleyin, ardından yeniden deneyin.
• 500, 503 ve ağ hataları: üstel geri çekilmeyle (1 sn, 2 sn, 4 sn) yeniden deneyin ve üç denemeden sonra vazgeçin.
• Diğer tüm hatalar (101 ile 103 arası, 105 ile 107 arası, 2xx doğrulama kodları, 300, 404): yeniden denemeyin. Bunun yerine isteği, anahtarı veya planı düzeltin.

104 ve 5xx hatalarını yeniden denemenin bir maliyeti yoktur, çünkü bu başarısız istekler ücretlendirilmez.

async function withRetry(fn, retries = 3) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retryable = err.code === undefined || err.code === 104 || err.code >= 500;
      if (!retryable || attempt >= retries) throw err;
      const delay = err.retryAfter ? err.retryAfter * 1000 : 1000 * 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

const data = await withRetry(() => metalapi("latest", { currencies: "XAU,XAG" }));