معالجة الأخطاء

صيغة استجابة الخطأ

عند فشل الطلب، تستجيب الواجهة بحالة خطأ HTTP وجسم JSON يحتوي على success: false. ويتضمن الكائن error رمزًا رقميًا في code، ونوعًا قابلًا للقراءة آليًا في type، ورسالة مفهومة للبشر في info:

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

اعتمد في منطق شيفرتك على code أو type، لا على نص info الذي قد يتغير. الرموز هي نفسها كما في الإصدارات السابقة من MetalAPI، لذا تستمر التكاملات الحالية في العمل.

أخطاء المصادقة والحساب

• 101 no_api_key (401): لا يحتوي الطلب على مفتاح API.
• 102 invalid_api_key (401): المفتاح غير معروف أو تم إلغاؤه.
• 103 account_inactive (403): الحساب غير نشط. تواصل مع الدعم.
• 107 origin_not_allowed (403): استُخدم مفتاح مقيّد بالنطاق من موقع ليس ضمن قائمة النطاقات المسموح بها.

أخطاء الحدود والخطط

• 104 too_many_requests (429): تم بلوغ حد الطلبات في الدقيقة. انتظر عدد الثواني المذكور في ترويسة Retry-After.
• 105 quota_exceeded (429): استُنفدت الحصة الشهرية حتى اليوم الأول من الشهر التالي (UTC).
• 106 plan_restriction (403): نقطة النهاية أو المعامل غير مشمول في خطتك، مثل /carat في خطة Free أو XAU-BID في الخطط الأدنى من Standard.

أخطاء التحقق

تُرجع هذه الأخطاء حالة HTTP 400، وتعني أن الطلب نفسه يحتاج إلى تصحيح:

• 201 invalid_base: رمز base غير معروف.
• 202 invalid_from و203 invalid_to: رمز from أو to غير معروف في /convert.
• 204 invalid_amount: المعامل amount مفقود أو ليس رقمًا.
• 205 invalid_date: تاريخ بصيغة غير صحيحة، أو تاريخ في المستقبل.
• 206 invalid_timeframe: المعامل start_date أو end_date مفقود، أو تاريخ البداية بعد تاريخ النهاية.
• 207 timeframe_too_long: النطاق أطول مما تسمح به خطتك (30 يومًا في Free، و365 يومًا في الخطط المدفوعة).
• 208 invalid_symbols: لا يوجد أي من الرموز المطلوبة.
• 209 invalid_unit: قيمة unit غير مدعومة.
• 210 invalid_carat: عيار غير مدعوم.

في currencies، تُتجاهل الرموز غير المعروفة ما دام رمز واحد على الأقل صالحًا.

أخطاء أخرى

• 300 no_results (404): الاستعلام صالح لكن لا توجد بيانات، كتاريخ يسبق بداية سجل الرمز.
• 404 invalid_function (404): نقطة نهاية غير معروفة. تحقّق من عنوان URL.
• 500 server_error (500): خطأ غير متوقع من جهتنا.
• 503 service_unavailable (503): بيانات الأسعار غير متاحة مؤقتًا.

معالجة الأخطاء في الشيفرة

تحقّق من success في كل استجابة وحوّل حالات الفشل إلى أخطاء يمكن لشيفرتك فحصها. تتعامل هذه الدالة المساعدة أيضًا مع الاستجابات غير المكتوبة بصيغة JSON القادمة من الخوادم الوكيلة:

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;
}

استراتيجية إعادة المحاولة

لا تُعِد المحاولة إلا في الأخطاء التي قد تنجح في محاولة ثانية:

• 104: انتظر عدد الثواني المحدد في Retry-After، ثم أعد المحاولة.
• 500 و503 وأخطاء الشبكة: أعد المحاولة مع تراجع أسي (ثانية، ثم ثانيتان، ثم 4 ثوانٍ)، وتوقف بعد ثلاث محاولات إعادة.
• كل ما عدا ذلك (من 101 إلى 103، ومن 105 إلى 107، ورموز التحقق 2xx، و300، و404): لا تُعِد المحاولة، بل أصلح الطلب أو المفتاح أو الخطة.

إعادة محاولة الأخطاء 104 و5xx لا تكلّفك شيئًا، لأن هذه الطلبات الفاشلة لا تُحتسب.

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" }));