رموز الأخطاء
تستخدم PolyTest API رموز حالة HTTP القياسية. تُرجع جميع استجابات الأخطاء جسم JSON يحتوي على حقل error يصف المشكلة.
صيغة استجابة الخطأ: تُرجع جميع الأخطاء كائن JSON بمفتاح واحد
"error" يحتوي على رسالة مقروءة. ويشير رمز حالة HTTP إلى فئة الخطأ.400Bad Request
الطلب مشوّه أو تنقصه معاملات مطلوبة.
{ "error": "timestamp query parameter is required" }الأسباب الشائعة
- معامل استعلام مطلوب مفقود
- صيغة معامل غير صالحة (مثل طابع زمني لا يتبع ISO 8601)
- قيمة معامل غير صالحة خارج النطاق المسموح
401Unauthorized
فشلت المصادقة — لا يحتوي الطلب على بيانات اعتماد صالحة.
{ "error": "Invalid API key" }الأسباب الشائعة
- ترويسة X-API-Key أو ترويسة Authorization مفقودة
- مفتاح API غير موجود أو غير صالح
- تم إبطال مفتاح API
- انتهت صلاحية مفتاح API
- رمز JWT غير صالح أو منتهي الصلاحية
403Forbidden
بيانات الاعتماد صالحة لكنها تفتقر إلى صلاحية هذا الإجراء.
{ "error": "Admin access required" }الأسباب الشائعة
- محاولة الوصول إلى نقاط نهاية مخصصة للمشرفين (sync، seed) دون صلاحيات المشرف
- نطاق مفتاح API لا يتضمن الصلاحية المطلوبة
404Not Found
المورد المطلوب غير موجود.
{ "error": "Market not found" }الأسباب الشائعة
- معرّف السوق غير موجود
- الـ slug الخاص بالسوق لا يطابق أي سجل
- لم يُعثر على لقطة ضمن ±2 ثانية من الطابع الزمني المحدد
429Too Many Requests
تم تجاوز حد المعدل. تمهّل وأعد المحاولة بعد الوقت المحدد.
{ "error": "Rate limit exceeded" }الأسباب الشائعة
- تم تجاوز حد الطلبات في الدقيقة لمستوى خطتك
- تم تجاوز حد الدفعات (طلبات كثيرة جدًا في نافذة قصيرة)
500Internal Server Error
حدث خطأ غير متوقع على الخادم. هذه الأخطاء نادرة — إذا استمرت، فتواصل مع الدعم.
{ "error": "Internal server error" }الأسباب الشائعة
- مشكلة في الاتصال بقاعدة البيانات
- فشل في خدمة المنبع
- استثناء غير متوقع على جانب الخادم
التعامل مع الأخطاء
أخطاء العميل (4xx)
لا تُعِد المحاولة تلقائيًا. أصلح معاملات الطلب أو المصادقة، أو تحقق من وجود المورد قبل إعادة المحاولة.
أخطاء الخادم (5xx)
يمكن إعادة المحاولة بأمان مع تراجع أُسّي. ابدأ بتأخير ثانية واحدة وضاعفه في كل محاولة حتى 3 إعادات.
import time
import requests
def api_request(url, headers, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 429:
wait = int(response.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait)
continue
if response.status_code >= 500:
time.sleep(2 ** attempt)
continue
return response
raise Exception("Max retries exceeded")