الأخطاء

كل فشل يستخدم نفس المغلّف الذي يستخدمه النجاح، مع data: null:

{
  "statusCode": 404,
  "errorCode": "not_found",
  "message": "Resource not found",
  "data": null
}

طابق على errorCode — فهو عقد ثابت. أما message فيمكن إعادة صياغته في أي وقت، وهو موجّه للسجلات والبشر، لا لعبارات if.

رموز الأخطاء

| errorCode | حالة HTTP | متى يحدث | | --- | --- | --- | | bad_request | 400 | الطلب مشوَّه: حقل مطلوب مفقود، قيمة غير صحيحة، limit خارج المدى، وما شابه. | | unauthorized | 401 | لا رمز وصول، أو رمز منتهٍ، أو المفتاح وراءه معطَّل أو محذوف أو مُستبدَل. راجع المصادقة. | | forbidden | 403 | الرمز صالح، لكن صلاحية المفتاح (أو دور المستدعي على هذا المورد تحديدًا) لا تسمح بهذا الإجراء. | | not_found | 404 | المورد غير موجود، أو يخص مؤسسة أخرى. هذان الاحتمالان متعمَّد عدم التمييز بينهما — فلا يمكن لمستدعٍ استخدام هذه الواجهة أبدًا لاستكشاف وجود شيء لا يملكه. | | conflict | 409 | الطلب يتعارض مع عملية جارية — حاليًا فقط idempotency_in_progress (أدناه). | | unprocessable_entity | 422 | الطلب صحيح الصياغة لكن لا يمكن تطبيقه — حاليًا فقط idempotency_key_reuse (أدناه). | | invalid_cursor | 400 | معامل الاستعلام cursor ليس قيمة أصدرتها هذه الواجهة. راجع شكل الاستجابة والتقسيم إلى صفحات. | | rate_limited | 429 | استنفدت المؤسسة حصتها من الطلبات في النافذة الحالية. راجع أدناه. | | payload_too_large | 413 | نص الطلب أكبر من 1 ميغابايت. | | internal_error | 500 | فشل شيء من جهتنا. لا يحتوي message أبدًا على تتبع مكدس (stack trace) أو نص استثناء — اقتبس ترويسة X-Request-Id عند التواصل مع الدعم. |

حدود المعدل

{
  "statusCode": 429,
  "errorCode": "rate_limited",
  "message": "...",
  "data": null
}

مع ترويسة Retry-After (بالثواني) تخبرك كم تنتظر. تُطبَّق الحدود لكل مؤسسة، ولكل دورة فوترة، وتشمل القراءات والكتابات معًا — استنفاد الحصة بالقراءات يحجب الكتابات أيضًا، والعكس صحيح. تراجَع وأعد المحاولة بعد فترة Retry-After بدل إعادة المحاولة فورًا؛ فإعادة المحاولة الفورية تستهلك طلبًا آخر يصطدم بالحد نفسه.

إعادة المحاولة بأمان

POST الذي ينشئ شيئًا ليس آمنًا لإعادة المحاولة عليه بشكل أعمى عند انتهاء مهلة الشبكة — فقد تُنشئ المورد مرتين. أرسل ترويسة Idempotency-Key في كل POST ينشئ موردًا، وإعادة المحاولة بنفس المفتاح مضمونة أن تعيد النتيجة الأصلية لا نسخة مكرَّرة. راجع شكل الاستجابة والتقسيم إلى صفحات للقواعد الدقيقة.

أما GET وPATCH وDELETE فآمنة عمومًا لإعادة المحاولة كما هي: GET بلا أي أثر جانبي، وإعادة PATCH/DELETE بعد نجاح محاولة سابقة إما تطبّق التغيير نفسه من جديد دون ضرر أو تعيد 404 not_found لمورد أصبح غير موجود — ولا واحدة من الحالتين تستحق معالجة خاصة.