تحمل كل استجابة من واجهة علاقات البرمجية رمز حالة HTTP. والتكامل الذي يقرأ هذا الرمز يفرّق بين طلب تستحق إعادة إرساله وطلب سيفشل بالطريقة نفسها في كل مرة، ويعرض الرسالة المناسبة على الشخص الذي عليه إصلاح المشكلة: مفتاح خاطئ، أو صلاحية ناقصة، أو باقة ممتلئة، أو قيمة غير صحيحة.
تسرد هذه الصفحة الرموز التي تُجيب بها الواجهة البرمجية ومعنى كل منها هنا، وتذكر صفحة كل نقطة نهاية الرموز التي قد تُرجعها تلك النقطة.
أرسل الترويسة Accept: application/json مع كل طلب، والترويسة Content-Type: application/json مع كل طلب له محتوى. فبدون
ترويسة Accept قد يعود الطلب المرفوض بإعادة توجيه أو بصفحة ويب بدلاً من خطأ JSON الموصوف هنا.
| الرمز | المعنى |
|---|---|
200 OK |
نجح الطلب. |
201 Created |
أُنشئ سجل، وهو ضمن data. |
206 Partial Content |
نجح طلب القائمة وتتبعه صفحات أخرى. اقرأ الصفحة التالية من links.next، راجع الصفحات. |
تعامل مع 206 على أنه نجاح، فهو ليس خطأً بل علامة على أن القائمة لم تنتهِ.
يُجيب الخطأ بكائن JSON يشرح الحقل message فيه ما حدث:
{
"message": "Unauthenticated."
}
ويحمل الرمز 422 أيضاً الحقل errors، وفيه مدخل لكل حقل فشل في التحقق مع أسباب فشله:
{
"message": "The title field is required. (and 1 more error)",
"errors": {
"title": [
"The title field is required."
],
"items.0.quantity": [
"The items.0.quantity field is required."
]
}
}
الرسائل مكتوبة للمطوّرين وقد تتغير صياغتها، لذا احكم على ما تفعله من رمز الحالة وأسماء الحقول، لا من نص الرسالة.
| الرمز | المعنى | ما تفعله |
|---|---|---|
| 400 | الطلب صحيح، لكن لا يمكن تنفيذه كما أُرسل. مثلاً: لا قيمة لدى جهة الاتصال لخاصية يستخدمها متغير في القالب، أو رفض واتساب الرسالة. وتشرح الرسالة السبب. | أصلح السبب الذي تذكره الرسالة، ثم أرسل الطلب مجدداً. |
| 401 | مفتاح API غير موجود، أو غير صحيح، أو منتهي الصلاحية، أو ملغى. | تحقق من الترويسة Authorization، أو أنشئ مفتاحاً جديداً. راجع المصادقة. |
| 402 | وصل الحساب إلى أحد حدود باقته، كعدد الخصائص المخصصة أو الملاحظات أو الردود الجاهزة، أو نفدت منه أرصدة يحتاجها الطلب، كرصيد رموز التحقق. | أفرغ بعض المساحة، أو اشترِ رصيداً، أو انتقل إلى باقة أكبر. راجع الباقات في صفحة الأسعار. |
| 403 | المفتاح لا يحمل الإمكانية التي تحتاجها نقطة النهاية، أو عضو الفريق الذي أنشأ المفتاح لا يملك صلاحية الإجراء، أو الإجراء غير مسموح على هذا السجل، كسجل لا يستطيع رؤيته أو خاصية يديرها نظام علاقات. وتميّز الرسالة بين هذه الحالات. | أضف الإمكانية إلى المفتاح، أو اطلب الصلاحية من أحد المسؤولين. راجع الصلاحيات والقدرات. |
| 404 | السجل غير موجود في حسابك، أو نقطة النهاية غير متاحة لمفاتيح API. | تحقق من قيمة _id ومن الرابط. ولا تقبل مفاتيح API إلا نقاط النهاية الموجودة في هذا المرجع. |
| 422 | فشل أحد الحقول في التحقق، ويذكر errors كل حقل. |
صحّح الحقول، ثم أرسل الطلب مجدداً. |
| 423 | عضو الفريق الذي أنشأ المفتاح معطّل في الحساب، أو الحساب مجدول للحذف. | اطلب من أحد المسؤولين إعادة تفعيل عضو الفريق، أو إلغاء الحذف. |
| 429 | طلبات كثيرة جداً: إما بلغ الحساب حد معدل الطلبات، راجع نظرة عامة، وإما بلغ حداً خاصاً بنقطة النهاية، كالانتظار بين رمزي تحقق إلى الرقم نفسه. | انتظر، ثم أرسل الطلب مجدداً. وإذا حملت الاستجابة الترويسة Retry-After، فهي تذكر عدد الثواني التي تنتظرها. |
| 500 | حدث خطأ من جهتنا. | أرسل الطلب مجدداً بعد قليل. وإذا استمر الفشل، تواصل مع الدعم واذكر وقت الطلب. |
لا تُعِد إرسال الطلب كما هو إلا بعد 429 أو 500:
429، انتظر عدد الثواني المذكور في الترويسة Retry-After، أو دقيقة إذا لم تحملها الاستجابة.500، انتظر مدة أطول قليلاً قبل كل محاولة جديدة، وتوقف بعد بضع محاولات.أما بقية الأخطاء فتتكرر بالطريقة نفسها ما لم يتغير شيء: الطلب، أو المفتاح، أو صلاحيات عضو الفريق، أو الباقة. وإعادة إرسالها في حلقة متكررة لا تفعل إلا استهلاك حد معدل الطلبات.
{warning} قبل إعادة إرسال طلب إنشاء بعد
500، اعرض قائمة السجلات للتأكد من أن السجل الأول لم يُنشأ، وإلا فقد ينتهي بك الأمر بالسجل مرتين.