الأخطاء والحصة

تعامل مع مشكلات Narwhal حسب حالة HTTP ورمز ثابت قابل للقراءة آليًا.

تستخدم أخطاء REST application/problem+json. تحمل أخطاء أدوات MCP حقول تفاصيل الخطأ نفسها في المحتوى المنظم.

استجابة تتضمن تفاصيل الخطأ

تفرّع عند status الأولى و code ثانيًا. تعامل مع detail كنص تشخيصي مقروء للبشر، وليس قيمة برمجية ثابتة.

مشكلة RFC 9457

{
  "type": "https://narwhalapi.com/problems/series-not-found",
  "title": "Economics series not found",
  "status": 404,
  "detail": "No approved economics observations matched the request.",
  "code": "series_not_found",
  "request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50"
}

الحالات والرموز

الحالة	رمز عام	المعنى
`400`	`invalid_query`	الدولة أو الفترة أو أحد مدخلات الطلب الأخرى غير صالح.
`400`	`invalid_cursor`	مؤشر ترقيم الصفحات غير صحيح الصيغة أو يخص مرشحات مختلفة.
`400`	`invalid_pair`	عملتا from وto متطابقتان.
`401`	`invalid_api_key`	مفتاح Bearer مفقود أو مشوّه أو غير معروف أو غير نشط.
`403`	`plan_upgrade_required`	يتجاوز السجل المطلوب المدة التي تتيحها خطتك: 12 شهرًا لخطة Free و5 سنوات لخطة Basic. يشمل هذا الرمز أيضًا ميزات السوق المدفوعة وتواريخ التنبؤ الأحدث مما تسمح به خطتك.
`404`	`series_not_found`	لا توجد قراءات حالية أو تاريخية معتمدة تطابق الطلب.
`404`	`resource_not_found`	مورد الأمر المطلوب غير متاح.
`404`	`event_not_found`	لا يوجد حدث يطابق المعرّف.
`404`	`not_found`	لا يوجد إصدار في التقويم يطابق المعرّف.
`404`	`route_not_found`	مسار REST المطلوب غير موجود.
`404`	`tool_not_found`	أداة MCP المطلوبة غير عامة أو غير موجودة.
`404`	`calendar_not_published`	لم يُنشر تقويم البلد والسنة المطلوبين.
`404`	`commodity_not_supported`	رمز السلعة هذا غير متاح للأسعار الفورية أو أشرطة الأسعار.
`404`	`currency_not_supported`	لا تُسعَّر هذه السلعة بالعملة المطلوبة.
`404`	`subscription_not_found`	معرّف اشتراك التقويم غير معروف أو لا يخصك.
`404`	`physical_series_not_found`	لا توجد سلسلة أسعار فعلية تطابق المعرّف.
`404`	`palmoil_series_not_found`	لا توجد سلسلة لزيت النخيل تطابق المعرّف.
`404`	`webhook_request_failed`	وجهة Webhook غير معروفة، أو لا يمكن إعادة إرسال التسليم.
`405`	`method_not_allowed`	المسار موجود، لكنه لا يقبل طريقة HTTP المطلوبة.
`409`	`cursor_expired`	انتهت صلاحية المؤشر أو لم تعد لقطته متاحة. تستخدم مؤشرات التقويم والأحداث هذا الخطأ أيضًا. ابدأ من جديد دون المؤشر.
`409`	`physical_series_ambiguous`	يطابق المحدد أكثر من سلسلة واحدة.
`409`	`limit_reached`	بلغت الحد الأقصى لوجهات webhook في خطتك.
`413`	`request_too_large`	نص الطلب كبير جدًا.
`429`	`rate_limit_exceeded`	تم بلوغ حد الشبكة أو الحساب خلال الفترة الزمنية القصيرة؛ أعد المحاولة بعد المدة المحددة في `Retry-After`.
`429`	`quota_exhausted`	استخدم الحساب مخصصه الشهري من الطلبات.
`500`	`internal_error`	تعذر على Narwhal إكمال الطلب.
`503`	`api_disabled`	الوصول إلى البيانات العامة مغلق مؤقتًا.
`503`	`economics_unavailable`	لا يستطيع Narwhal تلبية الطلب بأمان استنادًا إلى منشور رسمي مقبول.
`503`	`calendar_coverage_unavailable`	يتعذر تقديم التقويم بأمان حاليًا.
`503`	`database_unavailable`	مخزن البيانات غير متاح مؤقتًا.
`503`	`rights_state_changing`	تعذر على Narwhal تأكيد بقاء إذن المصدر دون تغيير أثناء إعداد الاستجابة.
`503`	`predictions_unavailable`	لا يمكن تقديم بيانات التنبؤ بأمان حاليًا.
`503`	`upstream_unavailable`	لا يمكن قراءة بيانات الأسعار أو أسعار الصرف الآن.
`503`	`palmoil_unavailable`	لا يمكن تقديم بيانات زيت النخيل بأمان الآن.
`503`	`physical_price_unavailable`	لا يمكن تقديم بيانات الأسعار الفعلية بأمان الآن.
`503`	`physical_reference_unavailable`	لا يمكن تقديم بيانات السلاسل الفعلية بأمان الآن.
`503`	`rate_limiter_unavailable`	لم تتمكن Narwhal من التحقق من حد معدل الطلبات. أعد المحاولة قريبًا.
`503`	`command_unavailable`	تعذر إكمال أمر الحساب الآن.
`503`	`webhook_unavailable`	لا يمكن تقديم Webhook الآن.

ترويسات الحصة

تستهلك كل استجابة بيانات ناجحة الحصة مرة واحدة بالضبط وتتضمن:

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetX-RateLimit-Short-LimitX-RateLimit-Short-RemainingX-RateLimit-Short-Reset

توضّح الترويسات المعتادة حصة الطلبات البالغة 5,000، لكل شهر بتوقيت UTC. في الاستجابات المصادق عليها، توضّح ترويسات الفترة الزمنية القصيرة حد حساب Free البالغ 30 طلبًا في الدقيقة. تسمح حاوية منفصلة للحماية من إساءة الاستخدام بـ120 طلبًا في الدقيقة، مع دفعة تصل إلى 20 طلبًا لهوية شبكة واحدة؛ لذلك قد تُقيَّد طلبات العملاء الذين يتشاركون عنوانًا واحدًا معًا. والخطأ 429 rate_limit_exceeded يتضمن Retry-After للفترة الزمنية القصيرة التي تفرض التقييد؛ أما الخطأ 429 quota_exhausted فيتطلب الانتظار حتى بداية الشهر التقويمي التالي بتوقيت UTC. ولا تستهلك أي من الاستجابتين الحصة الشهرية.

سلوك إعادة المحاولة

لا تُعد المحاولة عند تلقي 400 حتى تصحيح الطلب.
لا تُعد المحاولة عند تلقي 401 بالمفتاح المرفوض نفسه.
إعادة المحاولة 429 بعد ذلك فقط Retry-After أو X-RateLimit-Reset.
أعد محاولة الطلبات التي لا يتغير أثرها بتكرارها بعد 500 أو 503 مع زيادة أُسّية لفترات الانتظار ضمن حد أقصى وإضافة تفاوت عشوائي إليها.
A 404 series_not_found قد لا يصبح متاحاً إلا بعد نشر إصدار رسمي مدعوم.

اطلب المساعدة

أرسل نقطة النهاية والوقت بتوقيت UTC والحالة وcode و request_id إلى دعم Narwhal API. لا تُضمّن مفتاح API أبدًا.

العودة إلى البدء السريع أو راجع مرجع واجهة API للاقتصاد.