الأخطاء

صيغة Problem Details وكل رمز قد تعيده الواجهة.

صيغة الأخطاء

كل خطأ كائن Problem Details (RFC 9457) بصيغة application/problem+json. اعتمد على status وcode؛ أما detail فنص إنجليزي قد يتغير.

صيغة الأخطاء
العضو	الوصف
`type`	دائمًا `about:blank`.
`title`	عنوان HTTP القياسي، بالإنجليزية.
`status`	رمز HTTP.
`code`	رمز ثابت تقرؤه الآلة.
`detail`	شرح بالإنجليزية لأغراض التطوير.
`request_id`	معرّف الطلب، وهو أيضًا في الترويسة `X-Request-Id`. اذكره عند الإبلاغ عن مشكلة.
`errors`	للخطأ `validation_failed` فقط: الرسائل حسب المعامل.

مثال

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "The API key is invalid or has been revoked.",
  "request_id": "…"
}

رموز الأخطاء

رموز الأخطاء
الحالة	الرمز	المعنى	ما العمل
`401`	`missing_api_key`	لا يوجد مفتاح في الترويسة `Authorization`.	أرسل `Authorization: Bearer` متبوعًا بالمفتاح.
`401`	`invalid_api_key`	مفتاح غير معروف أو غير صالح الصيغة أو منتهٍ أو ملغى، أو مشروع غير نشط.	تحقق من المفتاح في وحدة التحكم أو أنشئ مفتاحًا آخر.
`403`	`insufficient_scope`	لا يملك المفتاح الصلاحية التي يتطلبها هذا المسار.	أنشئ مفتاحًا بهذه الصلاحية.
`404`	`not_found`	مسار غير معروف، أو معامل مسار خارج القواعد.	تحقق من المسار والطريقة.
`404`	`place_not_found`	لا يوجد مكان بهذا المرجع في الفهرس.	أعد البحث: تتغير المراجع بين الفهارس.
`405`	`method_not_allowed`	طريقة HTTP غير مقبولة.	استخدم `GET`.
`422`	`validation_failed`	معامل مفقود أو لا يحترم قواعده.	صحّح المعاملات المذكورة في `errors`.
`429`	`rate_limited`	بلغ المشروع حد معدل الطلبات.	انتظر عدد الثواني المذكور في `Retry-After`.
`500`	`internal_error`	خطأ غير متوقع في الخدمة.	أعد المحاولة لاحقًا مع زيادة المهلة تدريجيًا، واذكر `request_id`.
`503`	`service_unavailable`	لم يُفتح الوصول التجريبي لمفاتيح المشروع بعد.	انتظر فتح وصولك دون إعادة المحاولة بشكل متكرر.
`503`	`locality_catalog_unavailable`	فهرس التجمعات السكانية غير متاح.	أعد المحاولة لاحقًا.
`503`	`locality_catalog_invalid`	رُفض فهرس التجمعات السكانية في فحوص السلامة.	أعد المحاولة لاحقًا.
`503`	`locality_catalog_unsearchable`	لا يحتوي الفهرس على أي تجمع سكاني قابل للبحث.	أعد المحاولة لاحقًا.
`503`	`place_catalog_unavailable`	فهرس الأماكن غير متاح.	أعد المحاولة لاحقًا.
`503`	`place_catalog_invalid`	رُفض فهرس الأماكن في فحوص السلامة.	أعد المحاولة لاحقًا.

إعادة المحاولة دون تفاقم المشكلة

لا تُعِد أبدًا طلبًا رُفض بـ 4xx دون تعديله، إلا بعد 429.
بعد 429، انتظر الثواني المذكورة في Retry-After.
بعد خطأ 5xx، أعد المحاولة مع زيادة المهلة تدريجيًا وبعدد محدود من المحاولات.