Pag-unawa sa Rate Limit at Error Handling sa Kencang.in API

Ang maayos na integration ay gumagana kapag normal ang lahat at alam din ang gagawin kapag tinanggihan ng server ang request. Tinatalakay ng artikulong ito ang dalawang karaniwang sanhi ng problema sa Kencang.in API integration: paglampas sa rate limit at maling pag-unawa sa error.

Paano gumagana ang rate limit

Nililimitahan ng rate limit ang request bawat minuto kada API key. Layunin nitong panatilihing matatag ang serbisyo para sa lahat ng user. Depende ang limitasyon sa plan: 60 request bawat minuto sa Pro, 300 sa Business; nasa page ng presyo ang detalye: presyo. Nagre-reset ang bilang bawat minuto (fixed window), hindi sliding window.

Kasama sa bawat tugon ang mga header:

• X-RateLimit-Limit: limitasyon bawat minuto para sa key mo.
• X-RateLimit-Remaining: natitirang request sa kasalukuyang minuto.
• Retry-After: lamang sa tugon 429, ang bilang ng mga segundo bago mo puwedeng subukang muli. Ang header na ito ay na-standardize sa MDN.

Mga diskarte upang maiwasang matamaan ng 429

1. Batching sa panig mo. Kung kailangan mong gumawa ng 500 link, huwag ipadala nang sabay-sabay. Ilagay sa queue at iproseso ayon sa limitasyon, halimbawa 50 bawat minuto na may pantay na pagitan.
2. I-cache ang resulta. Ang data na bihirang magbago, tulad ng isang listahan ng mga domain o mga detalye ng link, ay hindi kailangang hilingin nang paulit-ulit.
3. Gumamit ng paginated list endpoint sa halip na isa-isang tawagin ang mga detalye.
4. Subaybayan ang X-RateLimit-Remaining at kusang pabagalin ang request bago ito umabot sa zero.

Hawakan ang 429 na may exponential backoff

Kapag nakatanggap ng 429, sundin ang Retry-After. Kung nawawala ang header, gumamit ng exponential backoff: maghintay ng 1, 2, 4, 8 segundo, kasama ang random jitter para hindi subukang muli ng maraming kliyente sa parehong segundo. Ang pattern na ito ay malawakang inirerekomenda, kabilang ang sa Gabay sa muling pagsubok ng Google Cloud.

Mga error code at ang kanilang mga kahulugan

• 400 Masamang Kahilingan: hindi valid na JSON ang body o may nawawalang required parameter. Suriin ang Content-Type at payload structure.
• 401 Hindi awtorisado: nawawala, mali o revoked na ang API key. Huwag mag-retry; ayusin ang key.
• 403 Ipinagbabawal: mga feature na hindi kasama sa iyong plan, halimbawa mga branded domain sa Libreng plan, o naubos na ang buwanang quota ng link.
• 404 Hindi Natagpuan: Ang link ID ay wala o hindi kabilang sa iyong account.
• 429 Napakaraming Kahilingan: limitasyon sa rate. Maghintay at ulitin.
• 500/502/503: pansamantalang pagkagambala sa gilid ng server. Subukang muli gamit ang backoff, maximum na ilang beses, pagkatapos ay i-record ito para sa pagsusuri.

Bukod sa HTTP status, laging may laman ang response body na error at message. Ibinabalik ang business validation error, gaya ng "ginagamit na ang alias" o "na-block ang URL dahil mapanganib", na may status na 200 at error: 1. Kaya tingnan ang pareho. Ang mga pagsusuri sa seguridad ng URL ay ipinaliwanag sa artikulo seguridad ng maikling link.

Idempotency at duplicate

Kapag nag-timeout sa network ang POST request, hindi mo alam kung nagawa na ang link. Puwedeng makagawa ng dalawang link ang pag-uulit. Solusyon: gumamit ng deterministic na alias (halimbawa order ID). Kung mayroon na nito, magbabalik ang API ng error na "ginagamit na ang alias" at makukuha ng app mo ang umiiral nang link sa search endpoint sa halip na gumawa ng bago.

Kapaki-pakinabang na pag-log

I-log sa bawat call: endpoint, HTTP status, value ng X-RateLimit-Remaining, at message kapag pumalya. Huwag i-log ang API key. Makikita mo sa log ang pattern, halimbawa pagdami ng 429 tuwing 9 ng umaga kapag tumatakbo ang cron, saka mo paghiwa-hiwalayin ang iskedyul.

Kailan dapat mag-upgrade ng plan?

Kung madalas mong naaabot ang limitasyon sa log kahit may batching na, tanda iyon ng aktuwal na load, hindi bug. May 300 request bawat minuto at walang limitasyong link sa Business plan. Para sa mas mataas na pangangailangan, makipag-ugnayan sa amin para sa custom plan. Nasa artikulong ito ang pangunahing halimbawa ng code para sa tatlong wika: halimbawa ng API code, at kumpletong dokumentasyon sa page ng developer.

Mga karaniwang tanong

Kinakalkula ba ang limitasyon sa rate sa bawat account o bawat key?

Bawat API key. Kung marami kang integration, gumawa ng hiwalay na key para sa bawat isa para hindi maubos ng isang abalang integration ang quota ng iba, at mas madaling subaybayan ang paggamit sa dashboard.

Mabibilang ba ang mga tinanggihang kahilingan na may 429?

Hindi. Ang mga kahilingang tinanggihan dahil lumampas sila sa limitasyon ay hindi binabawasan ang susunod na minutong quota. Ngunit ang pagpapadala ng mga patuloy na kahilingan kapag na-throttle na ay nag-aaksaya ng mga mapagkukunan, kaya igalang ang Retry-After header.

Paano dagdagan ang limitasyon ng kahilingan?

Mag-upgrade sa Business plan para sa 300 request bawat minuto. Para sa mas mataas na pangangailangan, gaya ng integration na may milyun-milyong link, makipag-ugnayan sa amin para sa custom plan na may angkop na limitasyon.

Ibig bang sabihin ng 5xx error ay nawala ang link ko?

Hindi. Ang 5xx na error ay nagpapahiwatig ng pansamantalang pagkaantala sa pagproseso ng kahilingan, hindi pagkawala ng data. Subukan muli gamit ang backoff; Kung magpapatuloy ang outage nang higit sa ilang minuto, tingnan ang page ng status o makipag-ugnayan sa amin.