الأخطاء

مغلِّف الخطأ، وخريطة رموز الحالة، ورموز الأخطاء المشتركة.

تستخدم كل استجابة خطأ مغلِّفًا واحدًا:

{
  "error": {
    "code": "<machine_code>",
    "message": "<human text>"
  }
}

code سلسلة snake_case يقرأها الحاسوب. تفرّع بناءً عليها، لا على رمز الحالة وحده.
message سلسلة إنجليزية يقرأها الإنسان للسجلّات وعرضها للمطوّر.

تذكر صفحة كل عملية رموز code الدقيقة التي تصدرها تلك العملية.

رموز الحالة

الرمز	المعنى
`400`	فشل التحقّق من جسم الطلب أو الاستعلام.
`401`	لم تُقدَّم بيانات اعتماد صالحة.
`403`	بيانات الاعتماد صالحة لكنها لا تسمح بهذا الإجراء.
`404`	المورد غير موجود أو غير مرئي للمستدعي.
`409`	يتعارض الطلب مع الحالة الراهنة للمورد.
`429`	تجاوز حدّ المعدّل.
`500`	فشل الخادم في إكمال الطلب.

تظهر هذه عبر عمليات كثيرة:

الرمز	الحالة	المعنى
`invalid_body`	`400`	فشل التحقّق من جسم الطلب.
`invalid_input`	`400`	فشل التحقّق من حقل.
`unauthorized`	`401`	المصادقة مطلوبة.
`insufficient_scope`	`403`	يفتقر مفتاح الواجهة البرمجية إلى الصلاحية اللازمة.
`not_found`	`404`	المورد غير موجود أو غير مرئي.
`already_revoked`	`409`	المورد المستهدف ملغًى مسبقًا.
`rate_limit_exceeded`	`429`	طلبات أكثر من اللازم؛ راجع `Retry-After`.
`internal_error`	`500`	خطأ خادم غير متوقّع.

يحمل الرمز 429 ثلاث ترويسات:

تراجع حتى تنقضي مدّة Retry-After، ثم أعد الطلب نفسه.