الأخطاء
تتشارك الأخطاء غلافًا واحدًا (راجع النظرة العامة). اعتمد على code في التفرّع، وسجّل meta.request_id، وتعامل مع message كنص إنجليزي موجّه للبشر.
أخطاء العميل
Section titled “أخطاء العميل”| الرمز | الحالة | المعنى وما يجب فعله |
|---|---|---|
validation_failed |
400 | فشل حقل في التحقق. يسمّيه field؛ ويشرح details السبب. أصلح الحقل. |
bad_request |
400 | تعذّرت قراءة الطلب أصلًا: JSON مشوّه، أو تدفق Content-Encoding معطوب، أو جسم طلب منقطع. لا يوجد حقل لإصلاحه؛ افحص طبقة النقل. |
validation_error |
400 | أُرسلت X-Account-Id إلى نقطة نهاية تمنعها (/auth/login، /auth/refresh، /auth/swap-company، /auth/logout). |
cursor_expired |
400 | مؤشر الترقيم أقدم من 24 ساعة. ابدأ السرد من جديد. |
unauthenticated |
401 | رمز مفقود أو غير صالح. حدّث الجلسة أو افحص المفتاح. |
invalid_signature |
401 | لم يتحقق توقيع webhook. راجع Webhooks. |
forbidden |
403 | الرمز صالح لكنه يفتقر إلى الصلاحية. |
account_context_mismatch |
403 | X-Account-Id لا تطابق حساب الرمز. انحرف تصوّر العميل للشركة الحالية؛ أعد قراءته من الجلسة. |
not_found |
404 | المورد غير موجود أو يتبع حسابًا أو موقعًا آخر. لا تميّز API أبدًا بين الحالتين. |
conflict |
409 | تعارض في الحالة: قفل تفاؤلي، أو قيد تفرّد، أو إجراء غير مسموح في الحالة الحالية (مثل الكتابة في محادثة مدمجة). |
idempotency_key_conflict |
409 | أُعيد استخدام Idempotency-Key مع جسم طلب مختلف. |
payload_too_large |
413 | يتجاوز جسم الطلب الحد المسموح لعائلة نقاط النهاية هذه. |
unsupported_media_type |
415 | قيمة Content-Type خاطئة. |
unprocessable |
422 | JSON صالح، لكن قاعدة عمل رفضته (مثل فترة حجز خارج ساعات العمل). |
storage_quota_exceeded |
422 | بلغ الحساب حد التخزين في خطته. يحمل details القيم used_bytes وquota_bytes وrequested_bytes؛ حرّر مساحة أو رقِّ خطتك. |
rate_limited |
429 | أبطئ. التزم بـ Retry-After وdetails.retry_after_seconds. |
أخطاء الخادم
Section titled “أخطاء الخادم”| الرمز | الحالة | المعنى وما يجب فعله |
|---|---|---|
internal_error |
500 | فشل غير متوقع. أعد المحاولة مرة واحدة، ثم تواصل مع الدعم مع request_id. |
upstream_unavailable |
502 | تعذّر على البوابة الوصول إلى الخدمة إطلاقًا. إعادة محاولة قصيرة تنجح عادةً. |
service_unavailable |
503 | صيانة مخططة أو قاطع دائرة مفتوح. أعد المحاولة بعد المدة في الترويسة Retry-After. |
ai_vendor_out_of_funds |
503 | رفض مزوّد الذكاء الاصطناعي الاستدعاء لأسباب تتعلق بالفوترة (402 أو 429 خاص بالحصة من المزوّد). اشحن رصيد حسابك لدى المزوّد؛ إعادة المحاولة لن تفيد. |
upstream_timeout |
504 | لم تُجب الخدمة في الوقت المحدد. أعد المحاولة عند وجود retry_after. |
إعادة المحاولة
Section titled “إعادة المحاولة”أعد محاولة 429 و502 و503 و504 وأعطال الشبكة مع تراجع أسّي، وأرسل Idempotency-Key نفسه في إعادة المحاولة كي لا تُطبّق عملية الكتابة مرتين أبدًا. لا تعِد محاولة أخطاء 4xx غير 429.