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_idli arizachi allaqachon bor (fields.external_id). - Sessiya
initholatida boʻlmagan arizachi uchun soʻralgan — avval arizachini qayta tiklang. - Tekshiruv
ON_HOLDemas, eskirgan yoki uni boshqa tekshiruvchi koʻrib chiqmoqda. REDqarori ikkinchi tekshiruvchining tasdigʻini kutmoqda.- Dalolatnoma yakuniy boʻlmagan (
GREENyokiREDemas) tekshiruv uchun soʻralgan. - Xuddi shu
Idempotency-Keyli 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_limitedniRetry-Afterdan keyin,500,503va tarmoq xatolarini esa eksponensial kechikish bilan takrorlang (masalan, 1, 2, 4, 8 soniya, biroz tasodifiy qoʻshimcha bilan, bir necha urinishgacha).- Boshqa
4xxxatolarni oʻzgartirmasdan takrorlamang — avval soʻrovni yoki holatni tuzating. - Har bir
POST,PATCHvaDELETEbilanIdempotency-Keyyuboring va bitta amalni takrorlaganda oʻsha kalitni qayta ishlating. Takror javobdaIdempotent-Replayed: trueboʻladi.5xxjavoblar saqlanmaydi, shuning uchun server xatosidan keyingi takror qaytadan bajariladi. Autentifikatsiya bobiga qarang. - Agar yaratish soʻrovi
Idempotency-Keysiz 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.