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

حدود الطلبات

يسري الحدّان على الحساب كله: كل مفاتيحك ومساعدي الذكاء الاصطناعي المربوطين معًا.

• يمتلئ حد الدقيقة باستمرار: يعود طلب واحد كل ثانية، حتى 60 طلبًا.
• الحد اليومي نافذة مدتها 24 ساعة، لا يوم تقويمي. وتذكر الترويسة X-RateLimit-Reset-Day متى تنتهي.

ترويسات تحديد المعدل

تحمل كل إجابة على طلب بمفتاح صالح:

عند بلوغ حد ما، تكون الإجابة 429 rate_limited مع الترويسة Retry-After: انتظر هذا العدد من الثواني، ثم أعد إرسال الطلب.

وتحمل كل إجابة أيضًا، سواء أكانت خطأً أم لا، الترويسة X-Request-Id.

شكل الخطأ

تتبع الأخطاء التنسيق القياسي « problem details » (application/problem+json):

{
  "type": "https://gloriads.com/docs/api/errors#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "limit must be between 1 and 100.",
  "issues": [
    {
      "path": "limit",
      "code": "invalid_value",
      "message": "limit must be between 1 and 100."
    }
  ],
  "request_id": "req_8fK2mQ7xLp3nR9sT1vWy"
}

• اختبر code في برنامجك النصي. فهو لا يتغير أبدًا؛ أما detail فمكتوب للبشر وقد تتغير صياغته.
• تسرد issues كل معامل غير صالح. ولا تظهر إلا مع invalid_request.
• اذكر request_id عند تواصلك مع الدعم.

رموز الأخطاء

invalid_request · 400 — أحد المعاملات غير صالح: قيمة غير معروفة، أو رقم خارج النطاق، أو مؤشر صفحة ليس من إصدارنا. وتذكر issues أي معامل ولماذا.

api_key_in_query · 400 — أُرسل المفتاح في عنوان URL. أرسله في الترويسة Authorization، وأبطل ذلك المفتاح: فربما وصل بالفعل إلى أحد السجلات.

unauthorized · 401 — لا يوجد مفتاح، أو المفتاح خاطئ أو مُبطَل. ولا تذكر الإجابة أيهما، عن قصد.

subscription_inactive · 403 — انتهى اشتراك الحساب. وتعود الـ API إلى العمل فور تفعيل الاشتراك.

insufficient_scope · 403 — المفتاح غير مسموح له بالقراءة. وكل مفتاح يُنشأ اليوم يستطيع القراءة، لذا يُفترض ألا ترى هذا الرمز أبدًا.

not_found · 404 — لا توجد نقطة نهاية في هذا المسار، أو أن ما طلبته غير موجود في حسابك. وما ينتمي إلى حساب آخر يتلقى الإجابة نفسها.

method_not_allowed · 405 — لا تجيب الـ API إلا على GET، لأنها للقراءة فقط. وتسرد الترويسة Allow ما تقبله.

amazon_not_connected · 409 — تقرأ /targets و/ads و/reports/streaming-tv من Amazon لحظة طلبك، وAmazon Ads غير مربوط أو يلزم إعادة ربطه. أصلح ذلك من الإعدادات ← Amazon Ads في Gloriads.

rate_limited · 429 — تم بلوغ أحد الحدود. انتظر عدد الثواني المذكور في Retry-After.

internal_error · 500 — حدث خلل من جهتنا. حاول مرة أخرى لاحقًا؛ وإذا تكرر ذلك، فأرسل إلينا قيمة request_id.

amazon_unavailable · 502 — لم تستجب Amazon لـ /targets أو /ads أو /reports/streaming-tv، أو تعذّر عليها إعداد تقرير البث التلفزيوني. حاول مرة أخرى بعد بضع دقائق.

timeout · 504 — استغرقت الإجابة أكثر من 30 ثانية. اطلب كمية أقل في كل مرة.

القيم والصفحات

• null تعني « غير موجود »، ولا تعني الصفر أبدًا.
• القوائم الطويلة تأتي على صفحات. يحدد limit حجم الصفحة: من 1 إلى 100 (50 افتراضيًا)، أو حتى 1,000 (100 افتراضيًا) للحملات والمجموعات الإعلانية. وعندما تكون قيمة has_more هي true، أعد إرسال next_cursor في cursor للحصول على الصفحة التالية.
• قد تكون الصفحة أقصر من limit عندما لا يُبقي عامل تصفية إلا صفوفًا قليلة (المجموعات الإعلانية لحملة واحدة). واصل اتباع next_cursor حتى تصبح قيمة has_more هي false.