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

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

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

استجابة المشكلة

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

مشكلة RFC 9457

{
  "ok": false,
  "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",
  "instance": "/v1/economics/USA/cpi"
}

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

الحالة	رمز عام	المعنى
`400`	`invalid_query`	إدخال الدولة أو الفترة أو أي طلب آخر غير صالح.
`401`	`invalid_api_key`	مفتاح Bearer مفقود أو مشوّه أو غير معروف أو غير نشط.
`404`	`series_not_found`	لا توجد ملاحظات حالية أو تاريخية معتمدة تطابق الطلب.
`404`	`route_not_found`	مسار REST المطلوب غير موجود.
`404`	`tool_not_found`	أداة MCP المطلوبة غير عامة أو غير موجودة.
`405`	`method_not_allowed`	المسار موجود، لكنه لا يقبل طريقة HTTP المطلوبة.
`429`	`rate_limit_exceeded`	تم بلوغ حد الشبكة أو الحساب قصير النافذة؛ أعد المحاولة بعد `Retry-After`.
`429`	`quota_exhausted`	استخدم الحساب مخصصه الشهري من الطلبات.
`500`	`internal_error`	تعذر على Narwhal إكمال الطلب.
`503`	`api_disabled`	الوصول إلى البيانات العامة مغلق مؤقتًا.
`503`	`economics_unavailable`	لا يستطيع Narwhal تلبية الطلب بأمان استنادًا إلى منشور رسمي مقبول.
`503`	`database_unavailable`	مخزن البيانات غير متاح مؤقتًا.
`503`	`rights_state_changing`	تعذر على Narwhal تأكيد بقاء إذن المصدر دون تغيير أثناء إعداد الاستجابة.

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

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

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

تصف الترويسات المعتادة الـ 3,000- الحد الشهري للطلبات وفق UTC. في الاستجابات المصادق عليها، تصف ترويسات النافذة القصيرة حد الحساب المجاني البالغ 30 طلبًا في الدقيقة مع دفعة قدرها 5تسمح حاوية منفصلة للحماية من إساءة الاستخدام بـ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 والحالة والرمز و request_id إلى دعم Narwhal APIلا تُضمّن مفتاح API أبدًا.

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