راقب استخدام مفتاحك قبل أن تبلغ الحد
متابعة ترويسات الحصة أولًا بأول تخبرك متى يقترب الحد، قبل وقت طويل من رفض أي طلب فعليًا.
التعامل مع استجابة 429 دون فقدان الطلب
رمز الحالة 429 ليس من نوع الإخفاق نفسه الذي يمثله 400 أو 404. فهو يعني أن الطلب سليم الصياغة وكان سينجح، لكن حصتك للفترة الحالية قد استُنفدت.
شكل الاستجابة
HTTP/1.1 429 Too Many Requests
X-Quota-Limit: 2500
X-Quota-Used: 2500
X-Quota-Free-Remaining: 0
X-Credits-Remaining: 0.00
X-Quota-Reset: 2026-09-22T00:00:00Z
{
"status": "error",
"error": {"code": "quota_exceeded", "message": "Daily quota exceeded"}
}لا تتخلص من الطلب
الخطأ الأكثر شيوعًا هو معاملة 429 بالطريقة نفسها التي يُعامل بها 400، أي تسجيله كإخفاق والمضي قدمًا. فالاستعلام الأساسي الذي أراده المستخدم أو النص البرمجي لديك ما زال صالحًا تمامًا، ويحتاج فقط إلى أن يُنفَّذ لاحقًا أو ببيانات اعتماد مختلفة. ضع حمولة الطلب الأصلية في قائمة انتظار لإعادة المحاولة بدلًا من التخلص منها.
قراءة وقت إعادة التعيين
تخبرك الترويسة X-Quota-Reset في الاستجابة 429 بالضبط متى تُعاد الحصة اليومية. ويمكن لمهمة تعمل في الخلفية أن تنتظر حتى ذلك الوقت ثم تستأنف قائمة الانتظار، بدلًا من الاستطلاع المتكرر أو تخمين فاصل ثابت لإعادة المحاولة.
سيناريو ثانٍ يستحق التخطيط له
لا تعني 429 دائمًا أن حصة اليوم كلها قد نفدت. فإذا بلغت قيمة X-Key-IPs-Used قيمة X-Key-IPs-Limit، فقد يُرفض المفتاح مؤقتًا من عنوان مصدر جديد حتى لو كانت الطلبات من عناوينه المعتادة ستظل تنجح. والتحقق من الترويسة التي تفسّر فعلًا الاستجابة 429، أهو استنفاد الحصة أم حد خانات IP، يغيّر طريقة الإصلاح: انتظار إعادة التعيين في الحالة الأولى، وتقليل عدد الأجهزة المختلفة التي تستخدم المفتاح نفسه في الحالة الثانية.
طريقتان لتجاوز الحد الآن
إذا لم يكن الانتظار مقبولًا، فهناك خياران فوريان: شحن الرصيد المسبق الدفع بسعر 0.0001 € للطلب، أو الانتقال إلى مفتاح Unlimited بسعر 50 € شهريًا إذا كان هذا نمطًا متكررًا لا ذروة عابرة. وكلاهما يزيل السقف اليومي الذي تسبب في 429 من الأساس.
التمييز بين حدود المفتاح وحدود الشبكة
بما أن الحصة المجانية مشتركة على مستوى نطاق /24 كامل في IPv4 أو /48 في IPv6، فقد تحدث 429 بسبب زيارات من عناوين أخرى على الشبكة نفسها، لا بسبب استخدام مفتاحك فقط. افحص X-Quota-Network-Used إلى جانب X-Quota-Used للتمييز بين الحالتين قبل أن تقرر ما إذا كانت ترقية المفتاح ستصلح أي شيء فعلًا.
خطأ يستحق التجنب
إعادة محاولة طلب فاشل فورًا، في حلقة متلاحقة، لحظة عودة 429 لا تضيف سوى المزيد من الطلبات الفاشلة فوق حصة مستنفدة أصلًا، دون أن تقربك أي خطوة من طلب ناجح. تراجع حتى وقت إعادة التعيين المذكور في الترويسة، أو إلى مهلة ثابتة معقولة إذا كان مسار الشيفرة لا يقرأ الترويسات، بدلًا من إغراق نقطة النهاية بالطلبات مجددًا على الفور.
معاملة 429 على أنها «أعد المحاولة بعد قليل» بدلًا من «هذا فشل» تُبقي قائمة الانتظار تتحرك بسلاسة عبر إعادة تعيين الحصة بدلًا من فقدان العمل. وتجد تفاصيل أشكال الأخطاء عبر واجهة API في صفحة الأخطاء، وخيارات الحصص الحالية في صفحة الأسعار.