رموز الأخطاء

كيف تُبلَّغ أخطاء API وردود SMTP، وما العمل حيال كل نوع.

تنسيق أخطاء API

أخطاء API بصيغة JSON برمز ثابت ورسالة. اعتمد على الرمز في منطقك البرمجي، واعرض الرسالة للأشخاص فقط، فقد تتغير صياغتها.

{
  "error": { "code": "invalid_recipient", "message": "The recipient address is not valid." }
}

إعادة المحاولة أم الإصلاح؟

تنقسم الأخطاء إلى مجموعتين. أصلح الطلب: استجابات 4xx عدا 429 تعني وجود خلل فيما أرسلته، فإعادة المحاولة ستفشل بالطريقة نفسها. حاول لاحقًا: استجابات 429 و5xx مؤقتة، فأعد المحاولة بتراجع أسّي مع حد لعدد المحاولات.

ردود SMTP

تبدأ ردود SMTP برمز من ثلاثة أرقام. 2xx تعني النجاح. 4xx تعني إخفاقًا مؤقتًا، فعلى المرسل إعادة المحاولة لاحقًا. 5xx تعني إخفاقًا دائمًا، فلا تعد إرسال الرسالة نفسها إلى ذلك العنوان. تضيف كثير من الردود رمزًا موسّعًا مثل 5.1.1 يوضح السبب.

قراءة أسباب الارتداد

الرموز الموسّعة أسرع وسيلة لفهم سبب الارتداد. 5.1.1 تعني أن صندوق البريد غير موجود. 5.2.2 تعني أن صندوق البريد ممتلئ. 5.7.1 تعني أن الخادم المستقبِل رفض الرسالة بموجب سياسة، وغالبًا بسبب التوثيق أو السمعة. أما رموز 4.x.x فمؤقتة وستُعاد محاولتها.

ماذا تفعل بحالات الارتداد

احذف العناوين ذات الارتداد الصعب من قائمتك، وافحص حالات الرفض بسبب السياسة بمراجعة إعدادات SPF وDKIM وDMARC. ارتفاع معدل الارتداد يضر بسمعتك، فتحرّك سريعًا.