رموز أخطاء الـ API: معناها وطريقة حلها

عندما يفشل طلب، يصلك رمز حالة HTTP ومعه رمز خطأ يحدد السبب. ابحث عن الرمز هنا لتعرف الخطوة التالية.

شكل رسالة الخطأ#

تأتي رسالة الخطأ بشكلين. فحوص المفتاح والرصيد والحدود تجري قبل استدعاء أي نموذج، وتردّ بجسم بسيط:

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

أما أخطاء تنفيذ الطلب فتتبع صيغة الواجهة التي استدعيتها، ومعها request_id تجده أيضًا في الترويسة X-Request-ID. الشكلان مع مثال لكل صيغة في أشكال الأخطاء.

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

حدود الاستخدام#

حدود الاشتراك#

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

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

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

• INSUFFICIENT_BALANCE: الرصيد لا يكفي للطلب. اشحن رصيدك ثم أعد المحاولة.
• API_KEY_QUOTA_EXHAUSTED: بلغ المفتاح حد الإنفاق الذي حدّدته له. ارفع الحد من إعدادات المفتاح.
• RATE_LIMITED: طلبات كثيرة في وقت قصير. انتظر قليلًا ثم أعد المحاولة.

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

• أخطاء 429 و5xx مؤقتة: أعد المحاولة بعد انتظار يتضاعف في كل مرة، وضع حدًا لعدد المحاولات.
• أخطاء 400 و401 و403 لا تختفي بإعادة المحاولة: أصلح الطلب أو المفتاح أو الرصيد أولًا.
• خطأ 429 بسبب حد الاشتراك لا يزول بإعادة المحاولة السريعة، بل يتجدد الحد في موعده.

ما زالت المشكلة قائمة؟#

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