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 ruxsatni Sozlamalar → Dasturchilar uchun → Tahrirlash orqali kalitga qo‘shing yoki yangi kalit yaratib, server sirini yangilang. Tahrirlash kalit nomi va ruxsatlarini joyida o‘zgartiradi; uning amal muddati va tokeni o‘zgarmaydi. OAuth orqali berilgan kalitlarni tahrirlab bo‘lmaydi; ilovaga berilgan ruxsatlarni o‘zgartirish uchun uni qayta ulang.

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.
• 503 outcome_unknownni hech qachon ko‘r-ko‘rona qayta urinmang. Avval resursni tekshiring; yangi idempotency kalitidan faqat o‘zgarish bo‘lmaganini tasdiqlagach foydalaning.
• Sabab o‘zgarmaguncha 400, 401, 403, 404, 413 yoki holat ziddiyatini qayta urinmang.

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