الترقيم، الثباتية، ومعالجة الأخطاء

يستخدم Ody API ترقيم المؤشر المعتم في نقاط نهاية القوائم الخاصة به، ورأس Idempotency-Key لإعادة محاولات إرسال الرسائل بأمان، وغلاف خطأ موحد واحد مع معرف طلب في كل استجابة — يغطي هذا الدليل الجوانب الثلاثة.

ترقيم المؤشر

GET /v1/api/contacts و GET /v1/api/conversations تستخدمان الترقيم مع ?limit= و ?cursor=:

curl "https://api.ody.co/v1/api/contacts?limit=100" \
  -H "Authorization: Bearer ody_live_…"

تتضمن الاستجابة nextCursor — مرره مرة أخرى كـ ?cursor= لجلب الصفحة التالية، وتوقف عندما تكون قيمته null:

{ "contacts": [ … ], "nextCursor": "eyJ…" }

• المؤشرات معتمة — مررها دائمًا حرفيًا؛ المؤشر المعدل أو القديم يعيد 400 invalid_argument.
• حدود حجم الصفحة: جهات الاتصال افتراضيًا 50، بحد أقصى 200؛ المحادثات افتراضيًا 50، بحد أقصى 100. GET /v1/api/messages/search (افتراضي 25، بحد أقصى 100) و GET /v1/api/calls (افتراضي 50، بحد أقصى 200) تأخذ ?limit= فقط، بدون مؤشرات.
• تتبع حزم SDK الرسمية nextCursor نيابة عنك باستخدام listAll() / list_all() — انظر البدء السريع لحزم SDK: TypeScript و Python.

إرسال الرسائل الثابتة

يتركك فشل الشبكة بعد POST /v1/api/messages دون معرفة ما إذا كانت الرسالة قد أُرسلت — إعادة المحاولة بشكل أعمى تخاطر بالإرسال المزدوج. أرسل رأس Idempotency-Key (أي سلسلة نصية تصل إلى 200 حرف، فريدة لكل إرسال منطقي) وتصبح إعادة المحاولات آمنة:

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

• يتم تخزين الاستجابة الناجحة الأولى لمدة 24 ساعة؛ أي إعادة محاولة بنفس المفتاح في تلك الفترة تعيد تشغيلها حرفيًا بدلاً من الإرسال مرة أخرى، مع رأس استجابة Idempotency-Replayed: true.
• استمد المفتاح من حدث عملك الخاص ("order-1042-shipped")، وليس قيمة عشوائية لكل محاولة — الهدف الأساسي هو أن تشاركه عمليات إعادة المحاولة.

غلاف الخطأ

تحمل كل استجابة خطأ نفس الشكل:

{ "error": { "code": "permission_denied", "message": "This API key is missing the 'messages:send' scope", "requestId": "req_…" } }

الحالة	الرمز	ماذا تفعل
400	invalid_argument	صحح الطلب — الرسالة توضح الخطأ
401	unauthenticated	المفتاح مفقود، غير صالح، أو تم إلغاؤه. لا تعاود المحاولة؛ نبه مالك التكامل
403	permission_denied	الرسالة تحدد النطاق المفقود — أنشئ مفتاحًا يمتلكه
404	not_found	المورد غير موجود في مساحة العمل هذه
409	failed_precondition	مساحة العمل لا تستطيع القيام بذلك بعد (مثل عدم وجود رقم نشط للإرسال منه). أظهره، لا تعاود المحاولة
429	resource_exhausted	تم تجاوز الحد الأقصى للمعدل — انتظر ثواني Retry-After، ثم أعد المحاولة مع التراجع الأسي
500	internal	أعد المحاولة مع التراجع الأسي والاضطراب؛ حدد عدد مرات إعادة المحاولة

معرفات الطلبات

تحمل كل استجابة — سواء كانت ناجحة أو خاطئة — رأس X-Request-Id، والذي يُعاد كـ requestId في نصوص الأخطاء. سجله جنبًا إلى جنب مع سجلات طلباتك الخاصة، واذكره عندما تتصل بالدعم: فهو يحدد الطلب الدقيق من جانبنا. يمكنك أيضًا توفير X-Request-Id الخاص بك (حتى 64 حرفًا، أحرف/أرقام/_/-) وسيعيده Ody، مما يسهل ربط عمليات إعادة المحاولة.

مقالات ذات صلة

• نظرة عامة على API والمصادقة
• حدود معدل API وأفضل الممارسات
• البدء السريع لحزم SDK: TypeScript و Python

---