Ruxsatlar va xatolar

Har bir ochiq API amali bitta aniq ruxsat talab qiladi. Shu ruxsati yo‘q haqiqiy hisob maʼlumoti 403 insufficient_scope oladi; unga kengroq kirish hech qachon yashirincha berilmaydi.

Ruxsatlar maʼlumotnomasi#

Hisobot vazifalari uchun o‘qish ruxsatlarini ishlating. Faqat integratsiya o‘sha o‘zgarishni bajarsa yozish ruxsatini qo‘shing. Masalan, lid eksportiga odatda sites:read va leads:read kerak, sites:write yoki agents:write emas.

Ruxsat xatolari#

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

Yetishmayotgan ruxsatli yangi kalit yarating va server sirini yangilang. Mavjud API kaliti ruxsatlarini joyida kengaytirib bo‘lmaydi; bu huquq o‘zgarishlarini aniq va audit qilinadigan qiladi.

Xato qobig‘i#

Barcha API xatolari bir xil yuqori darajadagi tuzilmani ishlatadi:

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

Inglizcha messageni taqqoslamasdan error.code bo‘yicha shoxlansin. Xabarlar versiya o‘zgarmasdan yaxshilanishi mumkin. Amal nomi, holat va urinish bilan error.request_id hamda x-request-id javob sarlavhasini log qiling, ammo authorization sarlavhasi yoki so‘rov sirlarini hech qachon yozmang.

Holat va kod maʼlumotnomasi#

Boshqa tenantdagi resurs mavjudligini oshkor qilmaslik uchun hisob egasidan tashqaridagi resurslar 404 qaytarishi mumkin.

Tekshiruv tafsilotlari#

Maydon tekshiruvi o‘z forma boshqaruvingiz yonida ko‘rsatish mumkin bo‘lgan yo‘llarni qaytaradi:

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

O‘zgartirish tanalari JSON obyekt bo‘lishi kerak. Array, bo‘sh tana, form data va text content type bilan yuborilgan JSON rad etiladi.

Qayta urinish qarorlari#

• 429dan keyin Retry-After ko‘rsatgan soniya kutib qayta urining.
• 500ni faqat xavfsiz o‘qish yoki bir xil Idempotency-Key bilan himoyalangan yozishda qayta urining.
• Jarayondagi idempotency 409 xatosidan keyin uning Retry-After: 2 sarlavhasiga ko‘ra qayta urining.
• Sabab o‘zgarmaguncha 400, 401, 403, 404 yoki holat ziddiyatini qayta urinmang.

Kutish tartibi uchun So‘rov tezligi cheklovlari, har amal ruxsati uchun API maʼlumotnomasiga qarang.