ابدأ من هنا
الأخطاء وإعادة المحاولة
حلّل غلاف أخطاء JSON القياسي وقرّر متى تكون إعادة المحاولة آمنة.
غلاف الخطأ
تستخدم إخفاقات واجهة JSON API كائن error واحدًا في المستوى الأعلى، يتضمن message مقروءة للبشر، وstatus برمز HTTP الرقمي، وcode ثابتًا اختياريًا. يشير عقد OpenAPI إلى هذا المخطط في حالات الإخفاق المتوقعة وغير المتوقعة.
{
"error": {
"code": "invalid_request",
"message": "A verified From domain is required",
"status": 403
}
}أخطاء العميل
صحِّح أخطاء الإدخال 400 قبل إعادة المحاولة. استبدل بيانات الاعتماد غير الصالحة أو ألغِها بعد 401. يتطلب 402 استحقاقًا مدفوعًا، ويشير 403 إلى حدّ سياسة أو صلاحية، ويعني 404 مورد مفقودًا ضمن نطاق المستأجر، ويمثّل 409 تعارضًا في الحالة أو في مفتاح عدم التكرار (idempotency key)، ويعني 413 تجاوز حدود المرفقات، ويغطي 422 إخفاق التحقق من الصحة أو المنع.
قرارات إعادة المحاولة
لا تُعِد المحاولة تلقائيًا عند إخفاقات المصادقة أو التحقق من الصحة أو المنع أو التعارض. يعني 423 أن هوية From المحددة متوقفة مؤقتًا؛ أوقف ذلك المسار، وصحّح قائمة مستلِميه، ولا تُعِد المحاولة إلا بعد أن تعود مقاييسه المتجددة إلى الحدود المقبولة. يمكن للمُستدعي إعادة المحاولة عند استجابة عابرة 429 أو 502 أو 503 باستخدام تراجع أُسّي محدود مع تشويش عشوائي (jitter). احتفظ بالقيمة نفسها لـ Idempotency-Key وبحمولة JSON مطابقة عند إعادة محاولة إرسال منطقي واحد.
سياق الدعم
سجّل وقت الطلب والمسار ورمز حالة HTTP ومعرّف مورد SendHQ وحقول الخطأ غير السرية. لا تُدرج أبدًا مفتاح API أو كوكي الجلسة أو نص الرسالة أو قائمة المستلِمين في بلاغ الدعم.