إنتقل إلى المحتوى الرئيسي

الحصص

نقطة /v1/quotas تُظهر ثلاثة أمور:

  1. حدود الخطة الأساسية (Free / Pro / غير محدودAPI / Enterprise) — ما يشتريه اشتراكك.
  2. أي تجاوزات ضبطها الدعم لمتجرك (صفقات مخصصة، تكاملات شركاء).
  3. الحدود الفعّالة — التجاوز يفوز، ويعود إلى افتراضيات الخطة عند غيابه.

GET /v1/quotas​

المصادقة: مفتاح منصة بصلاحية usage:read.

الطلب​

curl https://api.dzbuild.app/v1/quotas \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200​

{
  "data": {
    "tier": "pro_plus",
    "tier_limits": {
      "requests_per_month":  5000000,
      "signups_per_month":   50000,
      "webhooks_per_month":  500000,
      "requests_per_minute": 1200
    },
    "overrides": null,
    "effective": {
      "requests_per_month":  5000000,
      "signups_per_month":   50000,
      "webhooks_per_month":  500000,
      "requests_per_minute": 1200
    }
  }
}

عند وجود تجاوز:

{
  "data": {
    "tier": "pro",
    "tier_limits": {
      "requests_per_month":  500000,
      "signups_per_month":   5000,
      "webhooks_per_month":  50000,
      "requests_per_minute": 300
    },
    "overrides": {
      "requests_per_month":  2000000,
      "signups_per_month":   null,
      "webhooks_per_month":  null,
      "requests_per_minute": 600,
      "notes": "Partner integration — Q2 2026"
    },
    "effective": {
      "requests_per_month":  2000000,
      "signups_per_month":   5000,
      "webhooks_per_month":  50000,
      "requests_per_minute": 600
    }
  }
}

متى تطلب تجاوزًا​

  • ذروة موسمية بدون ترقية الشهر كاملًا (عيد، بلاك فرايدي).
  • تكامل شركاء — خدمة شبيهة بـ Zapier تتصل نيابة عنك وتحتاج RPS أعلى.
  • عقد مخصص — صفقات Enterprise.

تواصل مع الدعم بمعرّف متجرك لإعداد ذلك. التجاوزات صديقة للتاجر: ترفع السقف فقط ولا تخفضه.

-1 = غير محدود​

أي حقل قيمته -1 يعني بلا حد. خطة Enterprise تجعل الحقول الأربعة افتراضيًا -1. ومع ذلك يبقى سقف صلب requests_per_minute لحماية المنصة — 6000 لـ Enterprise إلا إن تم الاتفاق على معدل أعلى تعاقديًا.

متى تصطدم بحصة​

  • اندفاع في الدقيقة → 429 مع Retry-After.
  • حصة الطلبات الشهرية → 402 quota_exceeded حتى أول الشهر القادم.
  • حصة الاشتراكات → نفس 402 لكن تحجب فقط /v1/signups. باقي النقاط تعمل.
  • حصة Webhook → الـ webhooks الصادرة تتوقف حتى الإعادة؛ الواجهة الواردة تعمل عاديًا.

انظر الأخطاء وحدود المعدل لاستراتيجيات إعادة المحاولة.