/v1 هي application/problem+json (RFC 9457) بمجموعة ثابتة من الحقول:
code وليس على detail — فـcode عقد ثابت للتعامل الآلي، أما detail فهو مخصص للقراءة البشرية وقد يتغير. يظهر param عندما يكون الخطأ ناتجًا عن معلمة محددة في الطلب. أدرج request_id عند التواصل مع الدعم.
رموز الأخطاء
مجموعة الرموز مغلقة: فإضافة رموز جديدة تُعد تغييرًا في العقد العام ويُعلن عنها عبر سجل تغييرات الواجهة البرمجية. تشير الاستجابة
retryable: true إلى أن الحالة قد تزول، لكنها لا تثبت أن عملية الكتابة لم يكن لها أي أثر. أعد محاولة طلبات القراءة ضمن عدد محدود من المحاولات وميزانية زمنية محدودة، مع التراجع الأسي والتشويش العشوائي (jitter). التزم بـRetry-After عند وجوده، بما في ذلك عند ورود 409 أو 429 قابل لإعادة المحاولة.
بالنسبة إلى عمليات التعديل، اتبع عقد قابلية التكرار الآمن (idempotency) والاسترداد الموثّق للعملية. احتفظ بالمفتاح الأصلي والطلب الأصلي عند توفر الدعم لذلك. لا تُنشئ مفتاحًا جديدًا بعد انتهاء المهلة أو 5xx: فقد يؤدي ذلك إلى تكرار عملية كتابة ناجحة. ولا يوفّر الترويس Idempotency-Key أي حماية في عملية لا تدعمه.