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

أشكال الأخطاء ورموز الحالة وإرشادات إعادة المحاولة.

الأدلة مرجع 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 والوقت والمسار من دون المفتاح أو البيانات الحساسة.