الأرصدة والحدود

AstroWay يستخدم نموذج ائتمان بدلاً من عداد الطلبات البسيط.

هذا أكثر عدلاً: نقاط النهاية الخفيفة (/planets) تكلف 10 أرصدة، بينما الثقيلة (/rectification) تكلف 500.

نوعان من الحدود

1. ميزانية الائتمان اليومية/الشهرية

يعتمد عدد الأرصدة شهريًا على الخطة:

الخطة	أرصدة/شهر	الحد اليومي
Free	10,000	~333
Indie	50,000	~1,667
Starter	200,000	~6,667
Pro	800,000	~26,667
Business	3,500,000	~116,666
Enterprise	مخصص	مخصص

بمجرد استنفاد الأرصدة، تُرجع الطلبات اللاحقة 402 Payment Required (لخطة Free) أو تبدأ فوترة الاستخدام الزائد (لخطط Indie+).

2. حد المعدل (الطلبات في الدقيقة)

الخطة	RPM
Free	10 طلب/دقيقة
Indie	30 طلب/دقيقة
Starter	120 طلب/دقيقة
Pro	400 طلب/دقيقة
Business	1,000 طلب/دقيقة
Enterprise	مخصص

حد المعدل هو نافذة متغيرة. إذا أرسلت 120 طلبًا في 10 ثوانٍ، فستُرجع الطلبات التالية على هذا المفتاح 429 لمدة 50 ثانية.

إذا كان للمفتاح قائمة بالمصادر المسموح بها، فإن كل إدخال في القائمة يحصل على حصته من هذا الحد: حد المفتاح مقسومًا على عدد الإدخالات، ومقربًا لأعلى. لا يمكن لموقع واحد يحتوي على ويدجت مدمج أن يستهلك الحصة التي يدفع مالك المفتاح مقابلها، بينما تظل نطاقاته الأخرى عاملة. لا يزداد الحد الإجمالي للمفتاح: الحصص تقسمه ولا تُضاف إليه.

يتم احتساب العداد بناءً على الإدخال نفسه، وليس على المضيف الذي جاء منه الطلب. الإدخال *.example.com هو عداد واحد لجميع النطاقات الفرعية، وإلا فسيتم تجاوز القيود عن طريق إنشاء نطاق فرعي جديد لكل طلب. عندما يكون هناك إدخال واحد في القائمة، تكون الحصة مساوية للحد ولا يتغير شيء.

3. نقاط النهاية العامة (بدون مفتاح)

تُخدم 14 قاموسًا مرجعيًا /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) بشكل عام، بدون X-Api-Key وتكلف 0 أرصدة. الحد الأقصى هو 30 طلبًا/ساعة من عنوان IP واحد. تُعرض هذه البيانات أيضًا كموارد MCP astroway://reference/<slug> لوكلاء LLM.

ينطبق نفس الحد على بقية مساحات الأسماء العامة: /v1/public/*، /v1/embed/*، /v1/i18n/*.

حصة العرض من جانب الخادم

تم تصميم 30 طلبًا في الساعة للمتصفح: كل زائر يجلب عنوان IP الخاص به وحصته الخاصة. أما إذا كانت الطلبات تأتي من خادمك (مثل مكون إضافي لـ WordPress، أو SSR، أو تسخين ذاكرة التخزين المؤقت)، فإن عنوانًا واحدًا يخدم جميع الزوار ويستنفد الحد في غضون بضع عمليات إعادة تحميل للصفحة.

لهذه الحالة، أرسل رأس X-AstroWay-Site-URL مع عنوان الموقع:

X-AstroWay-Site-URL: https://example.com/

الوضع	الحد
بدون رأس	30 طلبًا / ساعة لكل IP؛ الويدجت `/v1/embed/*` لها حد منفصل 120 / ساعة لكل IP
مع رأس	300 طلبًا / ساعة لكل موقع، بحد أقصى 600 / ساعة لكل IP

الرأس مسموح به في CORS وليس بيانات اعتماد، لذا يظل الحد الأقصى لكل IP: بغض النظر عن عدد النطاقات التي يتم تسميتها من عنوان واحد، لن يتجاوز إجمالي الطلبات من هناك 600 طلب في الساعة. كلا العدادين مطلوبان في نفس الوقت: يعمل عداد الموقع عندما يأتي موقع واحد من عدة عناوين (CDN، موازن تحميل)، ويعمل عداد IP عندما تأتي العديد من الأسماء من عنوان واحد.

الاستدعاء الواحد ليس دائمًا وحدة واحدة. نقطة النهاية العامة الثقيلة تستهلك أكثر من السلة نفسها، ولا تحصل على سلة منفصلة. POST /v1/public/synastry تكلف 3، لأنها تتضمن خريطتين ومصفوفة جوانب من 45 خلية: الحد الأقصى العملي لها هو 10 في الساعة من عنوان غير معلن، و 100 لموقع معلن، و 200 لكل عنوان. كل شيء آخر يكلف 1. عندما يكلف الاستدعاء أكثر من وحدة واحدة، يذكر الرد ذلك في رأس X-RateLimit-Cost، ويتم رفض الاستدعاء الذي يكلف أكثر مما تبقى في السلة، بدلاً من أن يذهب إلى السالب.

يخبرك رأس الاستجابة X-RateLimit-Scope (ip أو site) أي العدادين هو الأكثر تقييدًا حاليًا. تصف رؤوس X-RateLimit-* الأخرى هذا العداد فقط، أي عداد واحد فقط من الاثنين. يظهر العداد الثاني في X-RateLimit-Counters:

X-RateLimit-Scope: site
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Counters: ip=597/600, site=297/300

التنسيق هو scope=المتبقي/الحد مفصول بفاصلة. يأتي الرأس فقط عندما يكون هناك عدادان بالفعل: استدعاء مجهول باستخدام X-AstroWay-Site-URL. يتم احتساب الاستدعاء بمفتاح مدفوع وفقًا لمفتاحك وخطتك، وهناك عداد واحد ولا يوجد رأس. اقرأه إذا كنت تقوم بالعرض من الخادم لعدة نطاقات من عنوان واحد: سلة الموقع لكل نطاق خاصة بها، ولكن الحد الأقصى لعنوان IP مشترك، وهو الذي يتم الوصول إليه أولاً.

قم بتخزين الردود مؤقتًا من جانبك: لا يتغير برجك اليومي خلال اليوم، ويحل التخزين المؤقت حتى منتصف الليل مشكلة الحد تمامًا.

مفتاح مدفوع على نقاط النهاية العامة. تعمل /v1/public/* و /v1/embed/* بدون مفتاح، ولكن إذا قمت بتمريره (X-Api-Key)، فسيتم احتساب الطلب وفقًا لخطتك، وليس وفقًا للحصة المجهولة، ولن يكون هناك علامة مائية مجانية في الرد. هذا منطقي للعرض من جانب الخادم: جهاز واحد يخدم جميع الزوار، و 300 طلب/ساعة مجهول غير كافٍ له.

جدول التكلفة

جدول شفاف كامل بجميع نقاط النهاية 771+ وتكلفتها - على صفحة تكلفة نقاط النهاية. لا تنشر DivineAPI/AstrologyAPI/Prokerala مثل هذا الجدول. مرجع سريع:

المستوى	أرصدة	الوقت النموذجي	أمثلة
1	10	< 50 مللي ثانية	`/planets`, `/moon-voc`, `/iching`
2	20	50–200 مللي ثانية	`/chart`, `/harmonics`, `/horary`
3	50	200–500 مللي ثانية	`/synastry`, `/progressions`, `/acg`
4	100	> 500 مللي ثانية	`/transit-calendar`, `/forecast-calendar`
5	250	عدة ثوانٍ	`/rectification/trutine`
6	500	حتى 120 ثانية	`/rectification`

رؤوس الاستجابة

تحتوي كل استجابة على:

X-Credits-Used: 20
X-Credits-Remaining: 9980
X-Credits-Limit: 10000
X-Credits-Reset: 2026-05-01T00:00:00Z
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1714521600
X-RateLimit-Origin-Limit: 60
X-RateLimit-Origin-Remaining: 59
X-Request-Id: 8aec43e9bc749b37e998a489bbad1757

X-Credits-Used: عدد الأرصدة المستهلكة لهذا الطلب
X-Credits-Remaining: الرصيد المتبقي من الميزانية الشهرية
X-Credits-Limit: إجمالي ميزانية الأرصدة الشهرية (حسب الخطة)
X-Credits-Reset: تاريخ ISO-8601 لتحديث الرصيد
X-RateLimit-*: الحالة الحالية للنافذة المتغيرة (تنسيق قياسي)
- X-RateLimit-Scope: أي عداد هو الأكثر تقييدًا حاليًا: ip، site أو key. تعني القيمة key أن الطلب تم احتسابه بمفتاحك ووفقًا لحد خطتك، وليس وفقًا للحصة المجهولة.
- X-RateLimit-Counters: على نقطة النهاية العامة، التي تم استدعاؤها باستخدام X-AstroWay-Site-URL، جميع العدادات التي تم احتساب الطلب بها، بتنسيق scope=المتبقي/الحد. تصف الرؤوس أعلاه العداد الأكثر تقييدًا فقط.
- X-RateLimit-Reset: اللحظة التي سيخرج فيها أقدم طلب من النافذة، أي عندما يصبح مكان واحد متاحًا. هذا ليس وقت الفتح الكامل للسلة: بعده سيمر طلب واحد، وسينتقل Reset إلى الطلب التالي زمنيًا. العميل الذي ينتظر حتى Reset ثم يرسل دفعة سيتلقى 429 مرة أخرى، لذا من الأفضل إرسال طلب واحد تلو الآخر أو تخزين الردود مؤقتًا من جانبك.
- الطلب المرفوض (429) لا يستهلك حصة ولا يحرك النافذة: يتم تجديد العداد فقط بالطلبات الناجحة.
- X-RateLimit-Origin-Limit و X-RateLimit-Origin-Remaining: تأتي فقط عندما يمر الطلب عبر إدخال من قائمة المصادر المسموح بها، وتظهر الحصة المخصصة لهذا الإدخال بالذات. الرفض بسبب هذه الحصة هو أيضًا 429، ويذكر النص الإدخال الذي تم استنفاده.
X-Subscription-Status و X-Subscription-Grace-Ends: تأتي فقط عندما تكون الفترة المدفوعة قد انتهت بالفعل، ولكن فترة السماح التي تبلغ 3 أيام لا تزال سارية (X-Subscription-Status: grace). يتم تقديم الطلبات وفقًا لخطتك حتى الوقت المحدد في X-Subscription-Grace-Ends، وبعد ذلك يكون الرد 402 SUBSCRIPTION_EXPIRED. إذا كان عميلك يسجل الرؤوس، فهذه هي الإشارة المبكرة بأن الوقت قد حان لتجديد الخطة.
X-Request-Id: معرف الطلب، 32 حرفًا سداسيًا عشريًا؛ اذكره عند الاتصال بالدعم.

كم تم استهلاكه بالفعل: ثلاث طرق

يمكنك التحقق من رصيد الأرصدة الحالي بثلاث طرق - من الأسرع إلى الأكثر تفصيلاً:

في كل استجابة: تُرجع الرؤوس X-Credits-Remaining / X-Credits-Used / X-Credits-Limit في أي طلب (حتى عند حدوث خطأ). لا تحتاج إلى استدعاء أي شيء إضافي - الرصيد دائمًا أمام عينيك.
بطلب منفصل: GET /v1/keys/usage مع X-Api-Key الخاص بك يُرجع credits (المستخدم / المتبقي / الحد / إعادة التعيين)، و usage (الطلبات لليوم / الأسبوع / الشهر)، وأفضل 20 نقطة نهاية خلال 30 يومًا. استدعاء واحد، بدون مفتاح مسؤول منفصل.
في لوحة التحكم: api.astroway.info/dashboard/billing تعرض الرصيد، ورسم بياني للاستخدام، وتفصيلاً حسب نقاط النهاية في الوقت الفعلي.

curl https://api.astroway.info/v1/keys/usage \
  -H "X-Api-Key: $AW_KEY"

التخزين المؤقت

تُرجع الطلبات المتطابقة خلال 5 دقائق من ذاكرة التخزين المؤقت دون خصم أرصدة. هذا رأس منفصل:

X-Cache: HIT
X-Credits-Used: 0

ما يعتبر “متطابقًا”:

نفس نقطة النهاية
نفس نص JSON (بايت-بايت بعد تطبيع المسافات)
نفس مفتاح API

هذا آمن، لأن جميع نقاط النهاية حتمية - نفس المدخلات تعطي دائمًا نفس المخرجات.

البث وخطافات الويب

البث (`/stream/*`)

يتم تسعير 10 نقاط نهاية للبث على أنها المستوى 1: 10 أرصدة لكل استدعاء. يعيد كل استدعاء حساب مواقع الكواكب، لذا فهو حساب كامل وليس بحثًا مخزنًا مؤقتًا - لا يوجد سعر “أرخص” منفصل لكل تيك.

تحتوي كل استجابة على حقلين للاستقصاء الاقتصادي:

tickSeconds: الفاصل الزمني الموصى به للاستقصاء؛
nextEventAt: متى ستتغير الحالة في المرة القادمة.

الاستقصاء بشكل متكرر أكثر من tickSeconds هو إهدار للأرصدة: لن تتغير الحالة حتى nextEventAt.

خطافات الويب (`/webhooks/*`)

تكلف عمليات CRUD لإدارة الاشتراك (/webhooks/subscribe، القائمة، العرض، الحذف، /test) المستوى 1: 10 أرصدة لكل منها. هذه استدعاءات نادرة.

تسليم الحدث (الخادم ← عنوان URL الخاص بك) لا يتم تسعيره: تُخصم الأرصدة فقط لاستدعاءات إدارة CRUD. يتم دعم 12 نوعًا من الأحداث (report-ready، transit-alert، eclipse-alert، dasha-change، sign-ingress، إلخ).

خطافات الويب متاحة من خطة Pro وما فوق.

ماذا تفعل عند تجاوز الحدود

`402 Payment Required`: نفدت الأرصدة

{
  "error": {
    "code": "credits_exhausted",
    "message": "Monthly credit budget exhausted. Upgrade plan or wait for reset.",
    "credits_remaining": 0,
    "credits_reset": "2026-05-01T00:00:00Z",
    "upgrade_url": "https://api.astroway.info/dashboard/billing"
  }
}

الخيارات:

ترقية الخطة: تحصل على ميزانية جديدة فورًا
الاستخدام الزائد (Starter/Pro): يتم تفعيله تلقائيًا إذا لم يتم تعطيله في الإعدادات
انتظار إعادة التعيين (Free): اليوم الأول من الشهر التالي

`429 Too Many Requests`: تجاوزت RPM

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "retry_after_seconds": 12
  }
}

الرأس Retry-After: 12 هو رأس HTTP قياسي، يجب أن يفهمه عميل HTTP الخاص بك.

المعالجة الصحيحة:

async function callWithRetry(endpoint: string, body: object) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'X-Api-Key': key, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return callWithRetry(endpoint, body);
  }

  return response.json();
}

تقدير الميزانية مقدمًا

قبل التكامل، قدّر عدد الأرصدة التي تحتاجها شهريًا:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

مثال: تطبيق يضم 500 مستخدم نشط يوميًا (DAU)، يقوم كل مستخدم بإجراء 3 حسابات خرائط + 1 تناغم في اليوم:

500 × (3 × 20 + 1 × 50) × 30 = 500 × 110 × 30 = 1,650,000 credits/mo
→ Enterprise (custom)

حاسبة الميزانية - على صفحة الخطط والأسعار.

الأخطاء: دليل كامل لأكواد الأخطاء
الثباتية: كيفية إجراء طلبات متكررة بأمان

هل كان مفيدًا؟

اقترح تعديلاً

آخر تحديث: 05‏/10‏/2026

// السابق

الجماتريا والأسماء الـ72

التالي //

التكلفة لكل نقطة نهاية