الأخطاء وإعادة المحاولة

تُعاد الأخطاء بصيغة JSON مع رمز error ثابت قابل للقراءة آلياً وحالة HTTP المطابقة.

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after_ms": 850
}

رموز الأخطاء

HTTP	`error`	إعادة المحاولة؟	ملاحظات
400	`invalid_request`	لا	فشل التحقق من معامل — صحّح الطلب.
401	`missing_api_key` / `unknown_api_key`	لا	راجع المصادقة.
403	`inactive_api_key` / `account_blocked`	لا	المفتاح مُعطّل أو الحساب موقوف.
402	`insufficient_credits`	لا	أعِد الشحن. يتضمّن الجسم `required` و`balance`.
429	`rate_limited`	نعم، بعد `retry_after_ms`	تجاوزت حدّك لكل دقيقة.
409	`request_in_progress`	نعم	لا يزال طلب متطابق غير قابل لإعادة التأثير قيد التشغيل.
422	(تعارض إعادة التأثير)	لا	أُعيد استخدام `Idempotency-Key` مع جسم مختلف.
503	`service_temporarily_unavailable` / `too_many_concurrent_requests`	نعم، مع تراجع تدريجي	حدّ سعة عابر.
504	`result_timeout`	نعم	تجاوز الجلب المنبع `deadline_ms`.

أعِد المحاولة عند 429 / 503 / 504 / 409 بتراجع تدريجي أسّي. عندما يكون retry_after_ms موجوداً، انتظر هذه المدة على الأقل قبل إعادة المحاولة.
لا تُعِد المحاولة أبداً عند 400 / 401 / 402 / 403 — لن ينجح الطلب حتى تغيّره.
تقوم حزم SDK الرسمية بالفعل بإعادة محاولة الأخطاء العابرة نيابةً عنك (محاولتان افتراضياً) وتُظهر راية retryable على الخطأ.