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