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

تأتي الأخطاء بالشكل التالي:

{
  "error": {
    "message": "Human-readable message",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request",
    "request_id": "req_..."
  }
}

اعتمد في منطقك على error.code لأنه ثابت، واعرض error.message للمطورين لا للمستخدم النهائي. ترويسة x-request-id تحمل المعرّف نفسه.

ماذا تفعل عند الخطأ

رموز الأخطاء

HTTP	`code`	المعنى	إعادة المحاولة؟
400	`invalid_request`	الجسم ليس JSON صالحًا أو حقل غير صالح	لا، صحّح الطلب
400	`context_length_exceeded`	المدخل أطول مما يسمح به النموذج	لا، اختصره
401	`invalid_api_key`	المفتاح مفقود أو غير معروف	لا
401	`revoked_api_key`	المفتاح أُلغي	لا، أنشئ مفتاحًا جديدًا
401	`expired_api_key`	المفتاح منتهي الصلاحية	لا، أنشئ مفتاحًا جديدًا
403	`project_archived`	المشروع مؤرشف	لا
403	`permission_denied`	المفتاح لا يملك صلاحية هذه النقطة	لا، غيّر صلاحيات المفتاح
404	`model_not_found`	معرّف النموذج غير موجود	لا، استخدم معرّفًا من `GET /v1/models`
404	`model_not_allowed`	النموذج موجود لكن المفتاح أو المشروع لا يستخدمه	لا
405	`method_not_allowed`	طريقة HTTP غير مدعومة على هذا المسار	لا
429	`rate_limit_exceeded`	بلغ المشروع حد الطلبات أو الرموز	نعم، مع backoff
429	`budget_exceeded`	الطلب سيتجاوز الميزانية الشهرية للمشروع	لا، ارفع الميزانية أو انتظر
429	`upstream_rate_limit`	بلغ مزود النموذج حده	نعم، مع backoff
402	`insufficient_credits`	حساب مزود النموذج بلا رصيد	لا، تواصل مع الدعم
502	`upstream_unavailable`	مزود النموذج غير متاح مؤقتًا	نعم
502	`provider_auth_error`	رفض المزود بيانات اعتماده	لا، تواصل مع الدعم
502	`upstream_model_not_found`	لم يُعثر على النموذج المضبوط لدى المزود	لا، تواصل مع الدعم
502	`invalid_upstream_response`	أرجع المزود استجابة غير قابلة للاستخدام	نعم، مرة أو مرتين
504	`upstream_timeout`	لم يجب المزود في الوقت المحدد	نعم
5xx	`output_limit_exceeded` و`server_misconfigured` و`database_error` و`internal_error`	مشكلة من جانب مبيان	أعد مرة واحدة ثم تواصل مع الدعم

ليس كل 429 آمنًا لإعادة المحاولة. budget_exceeded يرجع 429 أيضًا، وإعادته تكرر الفشل فقط. افحص error.code ولا تكتفِ بالرمز.

إعادة المحاولة

أعد محاولة rate_limit_exceeded وupstream_rate_limit وupstream_unavailable وupstream_timeout فقط، مع exponential backoff وjitter. لا تعِد محاولة أخطاء المصادقة أو الصلاحيات أو المشروع المؤرشف أو الطلب غير الصالح أو قيود النموذج دون تغيير الطلب أو الإعداد.

ترويسات حدود الاستخدام

تتضمن الاستجابات ترويسات تبيّن المتبقي من حد مشروعك:

الترويسة	المعنى
`x-ratelimit-limit-requests` و`x-ratelimit-remaining-requests`	حد الطلبات والمتبقي منه
`x-ratelimit-limit-tokens` و`x-ratelimit-remaining-tokens`	حد الرموز والمتبقي منه
`x-ratelimit-reset-requests` و`x-ratelimit-reset-tokens`	موعد إعادة ضبط النافذة

خفّف الطلبات قبل أن يصل remaining إلى الصفر بدل انتظار 429.

التواصل مع الدعم

احتفظ بقيمة x-request-id أو error.request_id (تبدو مثل req_...) عند التواصل مع الدعم. تربط بلاغك بالطلب نفسه في سجلات Platform.

الأدلة

نقاط النهاية

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

ماذا تفعل عند الخطأ

رموز الأخطاء

إعادة المحاولة

ترويسات حدود الاستخدام

التواصل مع الدعم

​ماذا تفعل عند الخطأ

​رموز الأخطاء

​إعادة المحاولة

​ترويسات حدود الاستخدام

​التواصل مع الدعم

ماذا تفعل عند الخطأ

رموز الأخطاء

إعادة المحاولة

ترويسات حدود الاستخدام

التواصل مع الدعم