حدود الـ API: الرصيد والمفتاح وحجم الطلب والسياق

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

الاشتراكات#

تعمل الاشتراكات في التطبيقات المدعومة، ولها حدّان فقط للاستخدام: حد الساعات الخمس والحد الأسبوعي. حين تبلغ أحدهما تجيب الطلبات بالحالة 429 والرمز USAGE_LIMIT_EXCEEDED إلى أن يتجدد الحد في موعده، ولا تفيد إعادة المحاولة السريعة. تعرض لوحة التحكم مقدار ما استخدمته من كل حد وموعد تجدده، والتفاصيل في حدود الاستخدام.

مفاتيح الدفع حسب الاستخدام#

حدود الاشتراك لا تنطبق هنا. ما يحدّ طلباتك:

• الرصيد: حين ينفد تجيب الطلبات بالحالة 403 والرمز INSUFFICIENT_BALANCE. اشحن رصيدك ثم أعد المحاولة.
• حد الإنفاق للمفتاح إن وضعته: الحالة 429 مع API_KEY_QUOTA_EXHAUSTED، أو insufficient_quota على /v1/responses. ارفع الحد من إعدادات المفتاح.
• تاريخ انتهاء المفتاح وقائمة عناوين IP المسموحة إن ضبطتهما: API_KEY_EXPIRED وACCESS_DENIED.

معدل الطلبات#

الطلبات الكثيرة في وقت قصير تجيب بالحالة 429 والرمز RATE_LIMITED. وتتباطأ أيضًا الطلبات المتكررة بمفتاح غير صحيح، مع الرمز INVALID_AUTH_RATE_LIMITED. انتظر، ثم أعد المحاولة بمهلة تتضاعف في كل مرة.

حجم الطلب#

الطلب الكبير جدًا يجيب بالحالة 413 والرمز REQUEST_TOO_LARGE، وسببه عادة صور أو ملفات كثيرة أو كبيرة. صغّر الصور، أو أرسل عددًا أقل في المرة الواحدة، أو ضع المستندات الطويلة في ملف وأرسل الأجزاء التي تحتاجها فقط. العناوين التي تحمل نصًا فقط، مثل Embeddings، تقبل أجسامًا أصغر من عناوين المحادثة.

طول السياق#

حين تكون المحادثة أطول من نافذة سياق النموذج يجيب الطلب بالحالة 400 والرمز CONTEXT_LIMIT_EXCEEDED. ابدأ محادثة جديدة، أو احذف الرسائل القديمة، أو لخّصها. نافذة السياق لكل نموذج:

أشكال الأخطاء#

تصلك الأخطاء بشكلين، بحسب مكان وقوعها.

من فحوص المفتاح والرصيد والحدود، قبل استدعاء أي نموذج:

{ "code": "INVALID_API_KEY", "message": "Invalid API key" }

وأثناء تنفيذ الطلب، بصيغة العنوان الذي استدعيته ومعها request_id، والمعرّف نفسه في الترويسة X-Request-ID. على العناوين المتوافقة مع OpenAI:

{
  "error": {
    "type": "invalid_request_error",
    "code": "CONTEXT_LIMIT_EXCEEDED",
    "message": "This conversation exceeds the model context limit. Start a new conversation or remove older content."
  }
}

على /v1/messages تكون الحقول نفسها داخل error مع "type": "error" في المستوى الأعلى، وفي صيغة Gemini يحمل الخطأ code رقميًا وmessage وstatus. أرسل request_id حين تتواصل معنا بشأن طلب فشل.

الرموز أثناء تنفيذ الطلب#

• INVALID_REQUEST · 400: تعذّر على النموذج معالجة الطلب كما أُرسل. راجع الحقول والقيم.
• CONTEXT_LIMIT_EXCEEDED · 400: المحادثة أطول من نافذة سياق النموذج. اختصرها.
• REQUEST_TOO_LARGE · 413: جسم الطلب كبير جدًا. أرسل صورًا وملفات أصغر أو أقل.
• RATE_LIMITED · 429: النموذج مشغول في هذه اللحظة. انتظر قليلًا ثم أعد المحاولة.
• MODEL_UNAVAILABLE · 503: النموذج غير متاح مؤقتًا. أعد المحاولة، أو اختر نموذجًا آخر.
• SERVICE_UNAVAILABLE · 503: مشكلة مؤقتة من جهتنا. أعد المحاولة بعد لحظات.
• AUTHENTICATION_FAILED · 503: مشكلة مؤقتة من جهتنا، لا علاقة لها بمفتاحك. أعد المحاولة بعد لحظات.
• UPSTREAM_TIMEOUT · 504: تأخر النموذج في الرد. أعد المحاولة، واستخدم البث مع المهام الطويلة.
• INTERNAL_ERROR · 500: خطأ غير متوقع. أعد المحاولة، وإذا تكرر فتواصل معنا ومعك request_id.

رموز فحوص المفتاح والرصيد والحدود في الأخطاء وحلولها.

متى تعيد المحاولة#

• الحالات 429 و500 و503 و504 مؤقتة: أعد المحاولة بمهلة تتضاعف في كل مرة، وضع حدًا لعدد المحاولات.
• الحالات 400 و401 و403 و413 لا تزول بإعادة المحاولة: أصلح الطلب أو المفتاح أو الرصيد أولًا.
• الرمز USAGE_LIMIT_EXCEEDED يزول حين يتجدد الحد، لا بإعادة المحاولة.