الاتفاقيات
المعرفات، والطوابع الزمنية، وبنية الخطأ، وإصدارات النسخ، ومحاولات الإعادة.
| الاتفاقية | قاعدة |
|---|---|
| المعرّفات | معرّفات UUID، غير شفافة. خزّنها كاملة؛ لا تحللها ولا تختصر أيًّا منها أبدًا |
| الطوابع الزمنية | RFC 3339 بتوقيت UTC، مثلًا 2026-09-22T04:10:00Z |
| الحقول غير المعروفة | تجاهلها. يمكن أن تصل حقول استجابة جديدة وقيم حالة جديدة دون زيادة رقم الإصدار |
| إدارة الإصدارات | السابقة تحمل الإصدار الرئيسي. أي تغيير كاسر يحصل على سابقة جديدة وإشعار مسبق |
| الأخطاء | {"description": "…", "error": {"error_code": "…", "error_attributes": {…}}} — فرّع على error.error_code، سجّل الوصف، ولا تطابقه أبدًا بناءً على نصه. انظر الأخطاء والحدود |
| إعادة المحاولة | التزم بـ Retry-After عند 429. وعند 5xx، أعد المحاولة مع تراجع أسيّ وتذبذب عشوائي |
عدم التأثير عند التكرار
أرسِل idempotency_key في كل تشغيل تبدأه. إنه سلسلتك أنت — رقم حلقة، معرّف مهمة، أي شيء ثابت لتلك الوحدة من العمل.
- المفتاح نفسه مع النص نفسه يعيد التشغيل الموجود بالفعل، بدلًا من بدء تشغيل ثانٍ.
- المفتاح نفسه مع نص مختلف يُرفض مع
idempotency_conflict. استخدم مفتاحًا جديدًا للعمل الجديد.
هذا يجعل إعادة المحاولة بعد انتهاء المهلة آمنة، وهو ما يميّز بين تشغيل واحد وتشغيل مكرر ستُحاسب عليه.
التتبع
كل استجابة تحمل x-morphic-trace-id. سجّله. عندما تُبلغ عن مشكلة، فإن ذلك المعرّف هو ما يتيح لنا العثور على التشغيل في ثوانٍ بدلًا من أن نطلب منك نافذة زمنية.