الأخطاء ورموز الحالة
الأخطاء بصيغة JSON، وبالشكل نفسه دائمًا، وتحمل دائمًا رمزًا ثابتًا مقروءًا آليًا. فرّع بحسب الرمز لا بحسب الرسالة.
الشكل
كل إخفاق يُرجع كائنًا يحوي error مقروءًا للبشر وcode ثابتًا. والرسالة مكتوبة لإنسان وقد تُعاد صياغتها؛ أما الرمز فالتزام ولن يتغيّر من تحتك.
{
"error": "That file is larger than the 200 MB limit on your plan.",
"code": "VALIDATION_FAILED"
}رموز ينبغي أن تعالجها
| الرمز | HTTP | المعنى |
|---|---|---|
| NOT_AUTHENTICATED | 401 | رمز bearer مفقود أو مُشوَّه |
| FORBIDDEN | 403 | المفتاح صالح لكنه غير مخوَّل بهذا |
| NOT_ENTITLED | 402 | خطة الحساب لا تشمل الوصول إلى واجهة البرمجة |
| VALIDATION_FAILED | 400 / 413 | طلب خاطئ، أو تحويل غير مدعوم، أو ملف أكبر من اللازم |
| NOT_FOUND | 404 | لا توجد مهمة بهذا المعرّف، أو أنها تخص حسابًا آخر |
| RATE_LIMITED | 429 | بلغتَ الحد الساعي. انتظر ثم أعد المحاولة. |
| INTERNAL | 500 | حدث خلل من جانبنا. إعادة المحاولة آمنة. |
ما الذي يستحق إعادة المحاولة
429 و500 يستحقان إعادة المحاولة مع تأخير — بتباعدٍ متزايد لا بحلقة متلاحقة، لأن المحاولات تُحتسب على حدّك الساعي كأي طلب آخر.
وما عدا ذلك نهائي لذلك الطلب. فإعادة محاولة 400 أو 402 أو 404 تُنتج الجواب نفسه وتستهلك حدّك لتكتشف ذلك.
502 أو 503 بلا متن JSON لم يأتِ من التطبيق — بل من الوسيط الذي أمامه، وهناك تستحق إعادة المحاولة دائمًا.