Asosiy qismga oʻtish
API hujjati API kalitini olish

Integratsiya · 9-bob

Xatolar

Har bir xato bir xil JSON shaklida va barqaror, mashina oʻqiydigan code bilan keladi. Xatolarni ishlashni HTTP holati va code ga quring, xabar matniga emas.

4 daqiqa oʻqish

Xato formati

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "fields": {
      "external_id": ["The external id field is required."]
    },
    "request_id": "req_01m6yyj5gq0x3c7d2n8v5kp4rt"
  }
}
Maydon Izoh
code Quyidagi jadvaldagi barqaror xato kodi
message Inglizcha, odam oʻqiydigan izoh. U oʻzgarishi mumkin; uni tahlil qilmang
fields Faqat validation_failed da: maydon nomi → xabarlar roʻyxati. Matnga emas, maydon nomiga tayaning
request_id X-Request-Id javob sarlavhasi bilan bir xil. Yordam markaziga murojaat yuborganda uni qoʻshing

HTTP holatlari

Holat Maʼnosi
200 / 201 Muvaffaqiyatli / yaratildi
202 Qabul qilindi: amal fonda davom etadi (arizachini oʻchirish, ikkinchi tekshiruvchini kutayotgan RED)
400 Soʻrov notoʻgʻri tuzilgan yoki tekshiruvdan oʻtmadi
401 API kalit yoʻq, notanish yoki bekor qilingan
403 Kalit toʻgʻri, lekin bu hisob uchun amalga ruxsat yoʻq
404 Topilmadi — yoki boshqa hisob yoxud muhitga tegishli
409 Joriy holatga zid
413 Fayl juda katta
422 Toʻgʻri tuzilgan, lekin bajarib boʻlmaydi
429 Soʻrov limiti yoki tarif limiti tugadi
500 Bizning tomonda kutilmagan xato
503 Bogʻliq xizmat vaqtincha mavjud emas

Xato kodlari

HTTP code Qachon Nima qilish kerak
400 bad_request Buzilgan JSON, notoʻgʻri Idempotency-Key formati, yaroqsiz parametr Soʻrovni tuzating
400 validation_failed Maydon yoʻq yoki yaroqsiz; fields ga qarang Koʻrsatilgan maydonlarni tuzating
401 unauthenticated API kalit yoʻq, notanish yoki bekor qilingan Authorization sarlavhasi va kalitni tekshiring
403 forbidden Hisob faol emas Yordam markaziga murojaat yuboring
403 tenant_not_verified Ishchi kalit biznes tasdiqlanishidan oldin ishlatilgan Biznes tasdiqlovini yakunlang — Sinov va ishchi rejim
404 not_found ID mavjud emas, boshqa hisob yoki muhitga tegishli, yoxud yoʻl notoʻgʻri ID va kalit muhitini tekshiring
409 conflict Amal joriy holatga mos emas (quyiga qarang) Joriy holatni oʻqing va unga qarab ish tuting
409 idempotency_conflict Bir xil Idempotency-Key boshqa soʻrov bilan ishlatilgan Yangi soʻrov uchun yangi kalit ishlating
413 file_too_large Yuklangan fayl limitdan katta Kichikroq fayl yuboring
422 unprocessable Notanish yoki oʻchirilgan flow; 10 tadan ortiq webhook endpointi Qiymatni tuzating yoki endpointlardan birini oʻchiring
429 rate_limited Soʻrovlar juda koʻp Retry-After soniya kuting va takrorlang
429 plan_limit_reached Tarifingizning ishchi rejimdagi oylik limiti tugagan Keyingi oyni kuting yoki tarifni oʻzgartiring
500 internal_error Kutilmagan xato Kechikish bilan takrorlang; davom etsa, request_id bilan Yordam markaziga murojaat yuboring
503 aml_unavailable Sanksiya tekshiruvi vaqtincha mavjud emas Keyinroq takrorlang
503 certificate_unavailable Dalolatnomani hozir yaratib boʻlmaydi Keyinroq takrorlang

409 conflict ning koʻp uchraydigan holatlari:

  • Bu muhitda shunday external_id li arizachi allaqachon bor (fields.external_id).
  • Sessiya init holatida boʻlmagan arizachi uchun soʻralgan — avval arizachini qayta tiklang.
  • Tekshiruv ON_HOLD emas, eskirgan yoki uni boshqa tekshiruvchi koʻrib chiqmoqda.
  • RED qarori ikkinchi tekshiruvchining tasdigʻini kutmoqda.
  • Dalolatnoma yakuniy boʻlmagan (GREEN yoki RED emas) tekshiruv uchun soʻralgan.
  • Xuddi shu Idempotency-Key li soʻrov hali bajarilmoqda.

Direct API xuddi shu qobiqdan oʻz kodlari bilan foydalanadi (masalan, invalid_file, image_too_large); ular uning bobida keltirilgan.

Hosted sahifa muddati oʻtgan, ishlatilgan yoki notanish sessiya havolasi uchun 410 qaytaradi, kyc.js esa onError da link_invalid, session_expired yoki network xabar qiladi. Bunday hollarda yangi sessiya yarating.

Soʻrov limitlari

Doira Limit
Barcha /api/v1 soʻrovlari API kalit uchun daqiqasiga 600 ta
include= li soʻrovlar (hujjat maʼlumotlari, shaxs) API kalit uchun daqiqasiga 30 ta
Webhook sinovi va yetkazishni takrorlash API kalit uchun daqiqasiga 10 ta
GET /documents/catalog (kalitsiz) IP uchun daqiqasiga 60 ta
Direct API IP uchun daqiqasiga 120 ta va kalit muhiti uchun daqiqasiga 60 ta

Javoblarda X-RateLimit-Limit va X-RateLimit-Remaining bor. Limitdan oshsa, soniyada berilgan Retry-After sarlavhasi bilan 429 rate_limited olasiz.

429 plan_limit_reached boshqa narsa: bu daqiqalik limit emas, ishchi rejimdagi oylik kvotangiz, va kvota boʻshamaguncha takrorlash foyda bermaydi. Uni GET /usage bilan tekshiring.

Qayta urinish va idempotentlik

  • 429 rate_limited ni Retry-After dan keyin, 500, 503 va tarmoq xatolarini esa eksponensial kechikish bilan takrorlang (masalan, 1, 2, 4, 8 soniya, biroz tasodifiy qoʻshimcha bilan, bir necha urinishgacha).
  • Boshqa 4xx xatolarni oʻzgartirmasdan takrorlamang — avval soʻrovni yoki holatni tuzating.
  • Har bir POST, PATCH va DELETE bilan Idempotency-Key yuboring va bitta amalni takrorlaganda oʻsha kalitni qayta ishlating. Takror javobda Idempotent-Replayed: true boʻladi. 5xx javoblar saqlanmaydi, shuning uchun server xatosidan keyingi takror qaytadan bajariladi. Autentifikatsiya bobiga qarang.
  • Agar yaratish soʻrovi Idempotency-Key siz vaqt tugashi bilan uzilgan boʻlsa, qayta yaratishdan oldin obyektni qidirib koʻring — masalan, GET /applicants?external_id=….
  • Qarorlar uchun soʻrab turishdan koʻra webhooklarni afzal koʻring. Webhook yetkazish taxminan bir kun davomida takrorlanadi — Webhooklar bobiga qarang.

Versiyalash

Versiya yoʻlning bir qismi: /api/v1. v1 ichida oʻzgarishlar faqat qoʻshimcha boʻladi:

  • yangi endpointlar, ixtiyoriy soʻrov maydonlari, javob maydonlari, webhook hodisa turlari, rad etish belgilari, tekshiruv nomlari va xato kodlari qoʻshilishi mumkin;
  • mavjud maydonlar, qiymatlar va kodlar qayta nomlanmaydi va olib tashlanmaydi.

Integratsiyangizni notanish maydonlarni eʼtiborsiz qoldiradigan va notanish qiymatlarni ehtiyotkorlik bilan ishlaydigan qilib yozing — masalan, notanish rad etish belgisini ON_HOLD kabi ishlang. Buzuvchi oʻzgarish yangi versiya (/api/v2) sifatida chiqadi.