وثائق API v1
العربية
لغة الوثائق أمثلة الشيفرة وأسماء الحقول متطابقة في جميع اللغات.
الدخول إلى لوحة التحكم

الخطوات الأولى

الأخطاء

عند حدوث خطأ، تستجيب API برمز حالة HTTP المناسب ونص استجابة يحتوي على code وmessage داخل error.

استخدم code في برنامجك. أما message فهو نص باللغة الإنجليزية يساعد من يتولى تصحيح الأخطاء، وقد يتغير.

صيغة الخطأ404
{
  "error": {
    "code": "not_found",
    "message": "Item not found or you do not have access to it."
  }
}
بلا مفتاح401
{
  "error": {
    "code": "missing_api_key",
    "message": "Send your API key in the X-API-Key header or as Authorization: Bearer <key>."
  }
}

رموز الأخطاء

الحالة الرمز متى يحدث
400 key_in_query أُرسل المفتاح في عنوان URL (المعاملات api_key أو apikey أو key أو token). أرسله في الترويسة وأنشئ مفتاحًا جديدًا، لأن المفتاح السابق ربما سُجّل في السجلات.
400 invalid_parameter أحد المعاملات له قيمة غير صالحة، مثل per_page بقيمة أكبر من الحد الأقصى.
401 missing_api_key لم يتضمن الطلب أي مفتاح.
401 invalid_api_key المفتاح غير موجود، أو تم إبطاله، أو أن مستخدمه معطَّل.
404 not_found نقطة النهاية غير موجودة، أو أن العنصر غير موجود أو يتبع مؤسسة لا يمكن للمستخدم رؤيتها.
404 organization_not_found قيمة organization المحددة لا تخص مؤسسة يمكن للمستخدم فيها رؤية هذا النوع من العناصر.
405 method_not_allowed لا تقبل API إلا GET (وHEAD).
429 rate_limited تم بلوغ حد الطلبات. انتظر عدد الثواني المحدد في Retry-After.
500 server_error خطأ داخلي. حاول مرة أخرى بعد قليل؛ وإذا استمر الخطأ، فتواصل مع الدعم.

متى تعيد المحاولة

لا تكرر الطلب نفسه إلا بعد 429 (مع انتظار Retry-After) أو 500. أما الأخطاء الأخرى فتتطلب تصحيح الطلب أو المفتاح.