الأخطاء وحدود المعدل
تُعيد كل نقطة نهاية في Watch-IP الأخطاء بالشكل نفسه، وتُطبِّق حدود المعدل بالطريقة نفسها، بصرف النظر عن المنتج الذي تستدعيه.
شكل استجابة الخطأ
أي استجابة ليست من فئة 2xx هي دائمًا كائن JSON يحتوي على error (رمز ثابت قابل للقراءة آليًا) وmessage (وصف قابل للقراءة من قِبل البشر). يبقى error ثابتًا عبر إصدارات الواجهة البرمجية؛ أما نص message فقد يتغير، لذا اعتمد في المطابقة على error لا على message.
استجابة الخطأ
{
"error": "invalid_ip",
"message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}رموز الحالة الشائعة
المجموعة الدقيقة من الرموز التي يمكن أن تُعيدها نقطة نهاية مُعينة موثَّقة في صفحتها المرجعية الخاصة؛ أما هذه فهي الرموز المشتركة عبر الواجهة البرمجية بأكملها.
- 400
- مُدخل غير صحيح التنسيق — عنوان IP غير صالح، أو دفعة فارغة أو تتجاوز الحد المسموح (يسمح POST /v1/lookup بما يصل إلى 100 عنوان IP)، أو حقل مطلوب مفقود.
- 401
- مفتاح API مفقود أو غير صالح.
- 403
- نوع مفتاح غير مناسب لهذا المسار (مفتاح قابل للنشر في نقطة نهاية تتطلب مفتاحًا سريًا، أو العكس)، أو — بالنسبة إلى GET /v1/geo وPOST /v1/email/validate فقط — Origin/Referer غير مدرج في قائمة النطاقات المسموح بها للمفتاح. وفي حالة النطاق، لا يتم تعيين ترويسة CORS أيضًا، لذا يحظر المتصفح الاستجابة بصرف النظر عن محتوى هذا النص.
- 422
- مُدخل صحيح دلاليًا لكن لا يمكن معالجته — حاليًا فقط في POST /v1/risk/check، عندما يتعذر تحديد موقع لعنوان IP المُقدَّم.
- 429
- تم تجاوز حد المعدل لنافذة الدقيقة الواحدة الحالية.
حدود المعدل
تُطبَّق حدود المعدل لكل حساب عميل ضمن نافذة ثابتة مدتها دقيقة واحدة، تُشارَك بين جميع نقاط النهاية التي تستدعيها بدلًا من تتبعها لكل مسار على حدة. يحتسب الحد استدعاءات HTTP لا العناصر: يُحتسب كل من POST /v1/lookup وPOST /v1/email/batch طلبًا واحدًا سواء حمل عنصرًا واحدًا أو 100 عنصر، وكذلك إنشاء مهمة قائمة بريد إلكتروني والاستعلام عن حالتها وتنزيل نتائجها. تتضمن استجابة 429 الناتجة عن حد المعدل (error: "rate_limit_exceeded") ترويسة Retry-After تحدد عدد الثواني المتبقية حتى إعادة ضبط النافذة الحالية — انتظر هذه المدة ثم أعد المحاولة.
إعادة المحاولة بأمان
تُعد كل من GET /v1/geo وGET /v1/lookup/{ip} وPOST /v1/lookup وPOST /v1/email/validate عمليات قراءة فقط، ويمكن إعادة محاولتها بأمان فورًا بعد خطأ في الشبكة. أما POST /v1/risk/check فيُحدِّث خط الأساس (baseline) المخزَّن افتراضيًا — مرِّر commit:false أولًا إذا احتجت إلى إعادة محاولة استكشافية لا ينبغي أن تُغيِّره.