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

رموز أخطاء واجهة نيزا وصيغ الردود، ومتى تعيد المحاولة ومتى لا تعيدها بعد انتهاء المهلة، حتى لا تتكرر العمليات.

الأدلة مرجع API أمثلة الكود أفضل الممارسات

الأخطاء

صيغة موحدة للأخطاء، مع توضيح ما يمكن إعادة محاولته وما يحتاج إلى تصحيح.

صيغة الخطأ

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": { "field": "eventName" },
    "requestId": "req_abc123"
  }
}

رموز HTTP وكيفية التعامل معها

الحقل	النوع	مطلوب	الوصف
400 / 422	Client error	لا تُعِد المحاولة	صحح JSON أو الحقول والقيم ثم أرسل طلبًا جديدًا
401	Authentication	لا تُعِد المحاولة	تحقق من المفتاح أو رمز Bearer والبيئة
403	Authorization	لا تُعِد المحاولة	الميزة غير مفعلة أو المفتاح لا يملك الصلاحية
404	Not found	لا تُعِد المحاولة	تحقق من المعرّف والمسار وحساب المنشأة
409	Conflict	حسب العملية	تعارض مع مورد أو حالة موجودة مسبقًا
429	Rate limit	أعد المحاولة	التزم بقيمة Retry-After، وأعد المحاولة بتأخير متزايد (backoff) مع تفاوت عشوائي (jitter)
5xx	Server error	أعد المحاولة	خطأ مؤقت؛ أعد المحاولة بعد مهلة مع تحديد عدد أقصى للمحاولات

معالجة آمنة في التطبيق

JavaScript

const response = await fetch(url, options);
const body = await response.json();

if (!response.ok) {
  const retryable = response.status === 429 || response.status >= 500;
  logger.warn({
    status: response.status,
    code: body.error?.code,
    requestId: body.error?.requestId,
  });
  if (!retryable) throw new Error(body.error?.message);
}

اعرض رسالة مناسبة للمستخدم ولا تعرض تفاصيل داخلية. عند مراسلة الدعم، أرسل requestId والوقت والمسار من دون المفتاح أو البيانات الحساسة.