النطاقات والأخطاء

تتطلب كل عملية في واجهة API العامة نطاقًا صريحًا واحدًا. وإذا كانت بيانات الاعتماد صالحة لكنها لا تملك هذا النطاق، فستتلقى الخطأ 403 insufficient_scope؛ ولا تتم ترقيتها أبدًا بصمت إلى صلاحيات أوسع.

مرجع النطاقات#

استخدم نطاقات القراءة لمهام إعداد التقارير. وأضف نطاق الكتابة فقط عندما ينفّذ التكامل هذا التعديل فعلًا. فعلى سبيل المثال، يحتاج تصدير الـ leads عادةً إلى sites:read وleads:read، لا إلى sites:write أو agents:write.

أخطاء النطاقات#

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}

أضف النطاق الناقص إلى المفتاح من الإعدادات ← المطوّر ← تعديل، أو أنشئ مفتاحًا بديلًا وحدّث السر المخزَّن على الخادم. يغيّر التعديل اسم المفتاح ونطاقاته في مكانه؛ أما تاريخ انتهاء صلاحيته والرمز المميّز فيبقيان كما هما. لا يمكن تعديل المفاتيح الصادرة عبر OAuth؛ أعد ربط التطبيق لتغيير ما مُنح من صلاحيات.

غلاف الخطأ#

تستخدم جميع أخطاء API البنية العليا نفسها:

type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};

اعتمد في المعالجة على error.code لا على message الإنجليزية، فقد تتحسن الرسائل دون تغيير الإصدار. سجّل error.request_id وترويسة الاستجابة x-request-id مع اسم العملية والحالة ورقم محاولة إعادة الطلب، لكن لا تسجّل أبدًا ترويسة التفويض أو أسرار الطلب.

مرجع الحالات والرموز#

قد تعيد الموارد الواقعة خارج حساب مالك بيانات الاعتماد الخطأ 404 بدلًا من الكشف عمّا إذا كان معرّف يخص مستأجرًا آخر موجودًا.

تفاصيل التحقق من الصحة#

يعيد التحقق من الحقول مسارات يمكن عرضها بجانب عناصر النموذج لديك:

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}

يجب أن تكون أجسام التعديل كائنات JSON. وتُرفض المصفوفات والأجسام الفارغة وبيانات النماذج وJSON المرسل بنوع محتوى نصي.

قرارات إعادة المحاولة#

• أعد محاولة 429 بعد عدد الثواني المحدد في Retry-After.
• أعد محاولة 500 فقط في عمليات القراءة الآمنة أو عمليات الكتابة المحمية بالمفتاح Idempotency-Key نفسه.
• أعد محاولة 409 الخاص بـ idempotency قيد التنفيذ بعد المدة الواردة في الترويسة Retry-After: 2.
• لا تعِد محاولة 503 outcome_unknown بشكل أعمى. تحقق من المورد أولًا؛ ولا تستخدم مفتاح idempotency جديدًا إلا بعد التأكد من أن التغيير لم يحدث.
• لا تعِد محاولة 400 أو 401 أو 403 أو 404 أو 413 أو تعارض الحالة إلا بعد تغيّر السبب.

راجع حدود المعدل لمعرفة سلوك التراجع، ومرجع API لمعرفة النطاق المطلوب لكل عملية.