API xətaları və retry qaydaları: necə qurulmalıdır

Qısa cavab

API xətalarının idarəsi bir sualdan başlayır: bu xətanı təkrar cəhd etmək mənalıdırmı? Müvəqqəti xətalar — server xətası (5xx), vaxt aşımı, «çox sorğu» (429) — artan fasilələrlə təkrarlanır. Daimi xətalar — səhv sorğu, icazə yoxdur, məlumat tapılmadı (əksər 4xx) — təkrarlanmır, çünki təkrar nəticəni dəyişmir; onlar düzəliş üçün insana çatmalıdır. Hər təkrar cəhdin limiti olur, limitə çatan sorğu itmir, ayrıca növbəyə (dead-letter) düşür, müəyyən hədd aşanda isə məsul şəxs bildiriş alır. Təkrar cəhd yalnız idempotentlik ilə birlikdə təhlükəsizdir.

Niyə xəta qaydası lazımdır

Qaydası olmayan inteqrasiyada iki ekstremal davranış olur. Birində xəta baş verəndə sorğu sadəcə itir: lead CRM-ə düşmür və heç kim bilmir. Digərində sistem xətanı dərhal və dayanmadan təkrarlayır — qarşı tərəf onsuz da yüklənibsə, bu təkrarlar onu tam dayandırır, «çox sorğu» limitinə görə hesab isə bloklana bilər.

Xəta qaydası bu iki ifratın ortasıdır: nəyi, nə vaxt, neçə dəfə təkrarlamaq və nə vaxt dayanıb insana xəbər vermək.

Xəta sinifləri

1. 1Müvəqqəti: təkrarlaServer xətaları (500, 502, 503, 504), vaxt aşımı, şəbəkə kəsilməsi.
2. 2Limit: gözlə və təkrarla429 «çox sorğu» — qarşı tərəfin dediyi qədər gözləmək (Retry-After başlığı).
3. 3Daimi: təkrarlama400 səhv sorğu, 401/403 icazə, 404 tapılmadı, 422 məlumat yoxlamadan keçmədi.
4. 4Naməlum: ehtiyatlaGözlənilməz cavab formatı — bir-iki təkrar, sonra insana.

Exponential backoff: artan fasilə

Təkrar cəhdlər bərabər fasilələrlə yox, artan fasilələrlə edilir: məsələn, 30 saniyə, 2 dəqiqə, 10 dəqiqə, 30 dəqiqə, 2 saat. Buna exponential backoff deyilir. Fasilələrə kiçik təsadüfi əlavə (jitter) qoyulur ki, eyni anda uğursuz olan yüzlərlə sorğu eyni anda təkrar gəlməsin. Qarşı tərəf «Retry-After» başlığı ilə nə qədər gözləmək lazım olduğunu deyirsə, həmin müddətə əməl olunur.

Limitlər: neçə dəfə və nə qədər

• Maksimum cəhd sayı: məsələn, 5–8 cəhd.
• Maksimum yaş: hadisə müəyyən vaxtdan köhnədirsə (məsələn, 24 saat), artıq göndərilmir — köhnə məlumat zərər verə bilər.
• Biznes mənası: bir saat gecikmiş «lead yarandı» bildirişi hələ faydalıdır, «müştəri zəngdə» bildirişi isə yox.
• Limitə çatan sorğu dead-letter növbəsinə düşür, silinmir.

Dead-letter növbəsi

Dead-letter növbəsi bütün cəhdləri bitmiş sorğuların saxlandığı yerdir. Orada hər sorğunun məlumatı, son xəta və cəhd tarixçəsi olur. Məsul şəxs səbəbi düzəldəndən sonra — məsələn, açarı yeniləyəndən sonra — sorğular yenidən göndərilir. Növbə boş qalmırsa və heç kim baxmırsa, o, sadəcə itən məlumatın daha səliqəli formasıdır: ona görə növbənin bir sahibi və həftəlik yoxlama vaxtı olmalıdır.

Bildiriş hədləri

Hər xəta bildiriş deyil — yoxsa komanda bildirişlərə məhəl qoymamağa öyrəşir. Praktik hədlər: icazə xətası (401/403) dərhal; dead-letter növbəsinə düşən ilk sorğu; son bir saatda uğursuz sorğuların payı müəyyən faizi keçəndə; qarşı sistem müəyyən müddət ümumiyyətlə cavab vermirsə. Bildiriş konkret adama və ya növbətçiyə gedir, ümumi qrupa yox, və bildirişdə nə etmək lazım olduğu yazılır.

Circuit breaker: qarşı tərəfi qorumaq

Qarşı sistem tam dayanıbsa, hər sorğunu təkrarlamaq onu bərpa olunanda da yükləyir. Circuit breaker qaydası belədir: ardıcıl uğursuzluqların sayı həddi keçəndə göndərmə müvəqqəti dayandırılır, sorğular növbədə gözləyir, bir müddət sonra bir sınaq sorğusu göndərilir və o uğurlu olanda növbə yavaş-yavaş boşaldılır.

AI söhbətində xəta: müştəriyə nə deyilir

AI söhbət zamanı API çağıranda — məsələn, sifariş statusu üçün — xəta müştərinin gözü qarşısında baş verir. Burada təkrar cəhd qısa olmalıdır: müştəri 30 saniyə gözləməz. Qayda əvvəlcədən yazılır: bir qısa təkrar, sonra dürüst cavab — «statusu indi yoxlaya bilmirəm, operator 15 dəqiqə ərzində sizə yazacaq» — və operatora bildiriş. AI heç vaxt xəta olanda statusu təxmin etməməlidir. Bu dizaynın detallarını çatbot API və webhook inteqrasiyası yazısında izah etmişik.

Təkrar cəhd və idempotentlik

Vaxt aşımı xətası ən çətin haldır: sorğu bəlkə də qarşı tərəfdə emal olunub, sadəcə cavab gəlməyib. Təkrar cəhd bu halda ikinci qeyd yarada bilər. Ona görə təkrar cəhd edilən hər əməliyyat idempotent olmalıdır — eyni açarla gələn ikinci sorğu ikinci nəticə yaratmamalıdır. Bunu sistemlər arasında dublikat məlumat yazısında ətraflı izah etmişik.

İllüstrativ nümunə

Bu, illüstrativ nümunədir. Təhsil mərkəzinin inteqrasiyası lead-ləri CRM-ə göndərir. Bir səhər CRM-in API açarının müddəti bitir və bütün sorğular 401 qaytarır. İnteqrasiya xətanı dayanmadan təkrarlayır, CRM hesabı «çox sorğu» səbəbindən bir saatlıq bloklanır, lead-lər isə itir.

Yeni qaydada 401 təkrarlanmır, dərhal IT-yə bildiriş gedir, sorğular dead-letter növbəsinə düşür. Açar yeniləndikdən sonra növbə yenidən göndərilir və heç bir lead itmir.

Tipik səhvlər

• Bütün xətaları eyni cür təkrarlamaq.
• Fasiləsiz, dərhal təkrar.
• Limit olmadan sonsuz təkrar.
• Dead-letter növbəsinə heç kimin baxmaması.
• İdempotentlik olmadan vaxt aşımını təkrarlamaq.

Məhdudiyyətlər

Ən yaxşı retry qaydası da qarşı tərəfin uzun dayanmasını həll etmir — o, yalnız məlumatın itməməsini və sistemlərin bir-birini yükləməməsini təmin edir. Rəqəmlər (cəhd sayı, fasilələr, yaş) biznes prosesinə görə seçilir və hər inteqrasiyada fərqli ola bilər. Qaydaları tələblər sənədində yazın — API inteqrasiyası tələbləri yazısında bölməsini göstərmişik.

Vexvon-da

Vexvon kanallardan gələn webhook-ların statusunu izləyir — gözləyir, işlənir, təkrar cəhd, uğursuz və s. — və uğursuz və ya asılı qalan webhook-ları yenidən işləyir. Vexvon-dan şirkətin sisteminə gedən webhook-lar və AI-nin çağırdığı şirkət API-ləri üçün isə təkrar cəhd, limit və müştəriyə veriləcək cavab inteqrasiya planında birlikdə razılaşdırılır. Ətraflı: inteqrasiyalar.

Növbəti addım

İnteqrasiyalarınızın son bir aylıq xəta jurnalını açın və xətaları dörd sinfə bölün. Hər sinif üçün indiki davranışı yazın: təkrarlanırmı, neçə dəfə, kim xəbər alır? Webhook-ların təkrar göndərilməsini webhook nədir yazısında izah etmişik. Digər yazılar enterprise inteqrasiya bölməsindədir; qaydalarınızı demo zamanı birlikdə yaza bilərik.