معالجة مشكلات تكاملات API

استخدم error.code وrequest_id في JSON. لا تشخص بتكرار الطلب الفاشل أو كشف بيانات الاعتماد.

1. أرسل طلب GET /school صغيراً.
2. عند 401 invalid_api_key تحقق من مصدر السر والانتهاء والإلغاء، ودوّر إن شككت.
3. عند 403 insufficient_scope قارن error.details.required_scope بقائمة المفتاح.
4. افحص إطلاق القراءة والكتابة المنفصل والميزة والتعليق والسياسة وشروط شبكة المصدر.
5. لا تعالج نطاقاً مفقوداً باستخدام مفتاح أوسع غير مرتبط.

• استخدم أسماء المرشحات وقيم التعداد الموثقة فقط.
• أرسل UUID صحيحاً وأوقات RFC 3339 بتوقيت UTC.
• لا تجمع created_after وupdated_after.
• أبقِ المؤشر مع نقطة النهاية ومعرّف المسار والمرشحات المعيارية نفسها.
• عند اجتياز غير صحيح أو منتهٍ، ابدأ بطلب أول جديد؛ ولا تعدل المؤشر.

• 415: أرسل application/json.
• 413: أبقِ الجسم عند 1 MiB أو أقل.
• 422: صحح المخطط أو قاعدة العمل الدقيقة.
• 409 idempotency_key_conflict: استُخدمت القيمة لطلب مختلف؛ لا تغير الطلب القديم ليلائمها.
• 409 idempotency_request_in_progress: انتظر Retry-After وأرسل الطلب والقيمة المطابقين.
• خطط التعلّم للقراءة فقط في API v1.

عند 429 احترم Retry-After وإعادة ضبط الحد. قلل الاستطلاع وزد حجم الصفحة ضمن الحد واستخدم المزامنة التزايدية. وعند 503 استخدم تراجعاً محدوداً؛ فقد تكون خدمة API أو السياسة أو الحصة المطلوبة غير متاحة مؤقتاً.

أرسل:

• الوقت بتوقيت UTC؛
• طريقة HTTP وقالب نقطة النهاية بلا قيم استعلام حساسة؛
• الحالة وerror.code وrequest_id؛
• اسم المفتاح أو معرّفه الآمن لا بيانات الاعتماد؛
• هل الفشل في القراءة أم الكتابة وهل يتكرر.

لا ترسل ترويسة التفويض أو المفتاح الخام أو قيمة منع التكرار الخام أو جسم بيانات شخصية كاملاً أو سجلات غير محجوبة. راجع الأخطاء والحصص و مرجع نقاط النهاية.