MASAR DEVELOPER PLATFORM

الأخطاء وحدود الطلبات

ابنِ تكاملك بحيث يتعامل مع الأخطاء والـRate Limit بطريقة قابلة للتنبؤ ولا يكرر الطلبات غير القابلة للنجاح.

v1.0Read-onlyHTTPSJSON

نموذج الخطأ

{
  "success": false,
  "code": "MAS-PERM-001",
  "message": "المفتاح لا يملك الصلاحية المطلوبة.",
  "data": null,
  "errors": {"required_scope": "gps:read"},
  "error": {
    "code": "MAS-PERM-001",
    "retryable": false,
    "correlation_id": "REQ-..."
  }
}

أكواد HTTP التي يجب التعامل معها

HTTP	المعنى	التصرف الصحيح
200	نجاح	استخدم `data`.
401	المفتاح غير صالح/منتهي/ملغى	لا تعاود الطلب آليًا؛ تحقق من المفتاح أو دوّره.
403	الخطة أو Scope لا يسمح	لا تكرر؛ عدّل الصلاحية أو الخطة.
404	المورد غير موجود ضمن المؤسسة	تحقق من المعرف ولا تفترض أنه تابع للمؤسسة.
429	تجاوز حد الطلبات	احترم `Retry-After` واستخدم Backoff.
503	الخدمة غير متاحة مؤقتًا	أعد المحاولة تدريجيًا ولا تستخدم حلقات سريعة.

Rate Limit

الحد يطبق لكل مفتاح. اقرأ الرؤوس التالية بعد كل طلب:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 41
X-RateLimit-Reset: 1780000000

Backoff مقترح

if status == 429:
    wait Retry-After seconds
else if status >= 500:
    retry with exponential backoff: 1s, 2s, 4s, 8s (max 4 attempts)
else:
    do not retry automatically

للدعم: أرسل وقت المشكلة، المسار، HTTP status، وX-MASAR-Request-Id. لا ترسل مفتاح API.