الأخطاء

الغلاف

كل إخفاق، أيًا كانت الحالة، هو كائن JSON واحد:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance",
    "request_id": "7f20a5f0-5dde-48cf-94aa-38acbbd218e0"
  }
}

code ثابت وقابل للقراءة آليًا. تفرّع عليه لا على message.
message شرح مقروء للبشر وقد يتغير.
request_id هو UUID الطلب. يُعاد أيضًا في الترويسة X-Request-ID في كل رد، نجاحًا كان أم فشلًا. اذكره عند الإبلاغ عن مشكلة.

في نقطة نهاية الرد المتدفق، الإخفاق الذي يحدث بعد بدء التدفق يصل كحدث error بنفس الحقول الثلاثة؛ راجع الرد المتدفق.

الرموز

HTTP	الرمز	المعنى
401	`invalid_api_key`	مفتاح مفقود أو مشوّه أو مجهول أو محذوف أو بسر خاطئ
403	`agent_mismatch`	المفتاح ينتمي إلى وكيل آخر
403	`permission_denied`	مفتاح `read-only` استدعى نقطة نهاية دردشة
403	`agent_disabled`	الوكيل مُطفأ. نقطتا نهاية الدردشة فقط
404	`agent_not_found`	الوكيل لم يعد موجودًا. نقطتا نهاية الدردشة فقط
404	`conversation_not_found`	محادثة مجهولة، أو ليست لهذا المفتاح
402	`insufficient_balance`	رصيد المالك لا يغطي الرد؛ لم يُخصم شيء
409	`idempotency_conflict`	استُخدم نفس `Idempotency-Key` بجسم مختلف
409	`idempotency_in_progress`	الطلب الأصلي ما زال جاريًا؛ أعد المحاولة بعد ثواني `Retry-After` (دائمًا `2`)
409	`conversation_busy`	رسالة أخرى للمستخدم الخارجي نفسه قيد الإجابة؛ أعد المحاولة بعد `Retry-After` (دائمًا `2`)
422	`validation_error`	جسم أو ترويسة أو تاريخ أو حد أو مؤشر غير صالح
429	`rate_limit_exceeded`	نافذة المفتاح مستنفدة؛ راجع حدود المعدل
503	`api_rate_limit_unavailable`	محدّد المعدل متوقف؛ يُرفض الطلب بدلًا من خدمته بلا قياس. أعد المحاولة بعد `Retry-After` (دائمًا `5`)
503	`service_unavailable`	خدمة خلفية تعتمد عليها API متوقفة؛ أعد المحاولة بعد `Retry-After` (دائمًا `2`)
500	`internal_error`	إخفاق غير متوقع؛ اذكر `request_id`

يُفحص agent_not_found وagent_disabled فقط في POST …/chat وPOST …/chat/stream. نقطتا نهاية GET لا تنظران إلى حالة الوكيل: مفتاح وكيل معطّل ما زال يستطيع عرض محادثاته وقراءة رسائله.

ما الذي يُعاد محاولته

أعد المحاولة بعد Retry-After بنفس Idempotency-Key

idempotency_in_progress، conversation_busy، rate_limit_exceeded، api_rate_limit_unavailable، service_unavailable. إعادة استخدام المفتاح تضمن ألا تدفع مرتين للرسالة نفسها.

أصلح الطلب أولًا

validation_error (اقرأ message؛ فهي تسمّي الحقل المخالف)، idempotency_conflict (استخدم مفتاحًا جديدًا للجسم الجديد)، permission_denied (استخدم مفتاح full)، agent_mismatch (استخدم الوكيل الذي ينتمي إليه المفتاح).

لا تعد المحاولة تلقائيًا

invalid_api_key (المفتاح حُذف أو السر خاطئ)، agent_disabled، agent_not_found، insufficient_balance (اشحن الرصيد أولًا). حلقة إعادة المحاولة على هذه الرموز لا تفعل سوى استنزاف حد المعدل.

أبلغ مع معرّف الطلب

internal_error. أعد المحاولة مرة واحدة بنفس Idempotency-Key: السجل الفاشل يُحرَّر، فتشغّل إعادة المحاولة الطلب من جديد بدلًا من إعادة نتيجة مخزّنة. هذا متوقع، لكنه ليس مضمونًا أن يكون مجانيًا. إذا حدث الإخفاق بعد أن أجاب النموذج بالفعل، تنتج إعادة المحاولة ردًا جديدًا وخصمًا جديدًا. إذا استمر الإخفاق، أرسل إلينا request_id.

ملاحظة حول 401

لا تفرّق API بين مفتاح محذوف ومفتاح لم يوجد قط: كلاهما invalid_api_key. إذا بدأ مفتاح كان يعمل بإرجاع 401، تحقق من بطاقة الوصول عبر API في التطبيق؛ فالأرجح أنه دُوِّر أو حُذف.

البداية

الأدلة

الغلاف

الرموز

ما الذي يُعاد محاولته

ملاحظة حول 401

​الغلاف

​الرموز

​ما الذي يُعاد محاولته

​ملاحظة حول 401

الغلاف

الرموز

ما الذي يُعاد محاولته

ملاحظة حول 401