الأخطاء والحدود

تحتوي أخطاء الإدارة على error (نص مقروء للبشر) وcode (ثابت). تفرّع بناءً على code وحالة HTTP، لا على نص الرسالة. قد تتضمن أخطاء الـ Scope الحقلين required وmissing_scope؛ وقد تتضمن الاستجابات القابلة لإعادة المحاولة retryAfter وretryable وRetry-After. إخفاقات الملكية تعيد 404 لتجنّب كشف موارد محفظة أخرى.

{ "error": "Insufficient scope", "code": "insufficient_scope", "required": "write" }

• 400: ‏JSON غير صالح، أو طلب غير صالح، أو وجهة مرفوضة.
• 401: مصادقة مفقودة/غير صالحة أو توقيع مرفوض.
• 402: ‏Credits غير كافية أو سعة Slot مطلوبة.
• 403: ‏Scope غير كافٍ أو تقييد صلاحية صريح آخر.
• 404: مورد مفقود أو غريب.
• 409: تعارض، أو حجز idempotency نشط، أو مفتاح معاد استخدامه، أو أصل متوقف مؤقتًا.
• 410: مسودة شحن منتهية الصلاحية.
• 422: فشل التحقق من الدفع.
• 429: حد المعدل أو استنفاد سعة الأمان الاحتياطية.
• 503: سعر أو موقّع (signer) غير متاح أو تبعية مؤقتة.

التزم بـ Retry-After واستخدم تراجعًا أسيًا (exponential backoff) مع jitter وميزانية محاولات محدودة. كرر العملية المتماثلة (idempotent) بالمفتاح نفسه والـ body نفسه. لا تكرر إخفاقات المصادقة أو الصلاحيات المرفوضة بشكل أعمى. لا تشترِ أبدًا اشتراكًا ثانيًا لمجرد انتهاء مهلة الاستجابة الأولى. جدّد عرض السعر أو المسودة فقط عندما تصبح التعليمة القائمة غير قابلة للاستخدام.

الـ challenge واستبدال الـ Token محدودان بـ 30 طلبًا في الدقيقة لكل IP. مسودات الشحن ومشتريات الاشتراك وإنشاء الـ watches محدودة بـ 10 في الدقيقة لكل محفظة. يسمح PATCH/DELETE للـ watch بـ 60 في الدقيقة؛ ويسمح PUT للإعدادات ومعاينة الرسائل بـ 30 في الدقيقة؛ ويسمح تصدير التنبيهات بـ 10 في الساعة. تُطبَّق الحدود قبل الـ Idempotency، بما في ذلك عمليات الإعادة. يُستخدم بديل احتياطي محدود محلي في العملية عندما يكون Redis غير متاح؛ وحدود الأمان تفشل بشكل مغلق عند استنفاد السعة الاحتياطية.

يتشارك إنشاء المستلمين وتغييرات الهدف 10 في الساعة لكل محفظة. لبريد التأكيد ميزانيات لكل محفظة ولكل وجهة قانونية (canonical). قد تعيد إعادة إرسال مخنوقة HTTP 200 مع sent: false بدلًا من 429؛ افحص ذلك الحقل. قد يبلّغ إنشاء المستلم عن confirmationSent: false. يبقى الهدف المعلّق غير متحقَّق منه ولا يمكنه تلقي الاختبارات أو التنبيهات.

يقبل دفتر الحساب وقائمة الـ watches limit وcursor مبهمًا. اتبع nextCursor حتى null؛ لا تفسّر الـ cursor ولا تعدّله. يستخدم سجل التنبيهات بدلًا من ذلك page تبدأ من الصفر وpageSize مع الفلاتر والفرز. التصدير محدود بـ 5,000 صف. لا تخلط بين نموذجي ترقيم الصفحات.

curl 'https://ftso.app/api/x402/watches?limit=20' \
  -H 'authorization: Bearer fbx_READ_TOKEN'
# Follow the returned nextCursor, URL-encoded, on the next request.

تُنشر قائمة الرموز الثابتة الكاملة في مستند OpenAPI. راجع مرجع العمليات للصلاحيات.