Memahami Had Kadar dan Pengendalian Ralat dalam API Kencang.in

Penyepaduan yang baik bukan sahaja berfungsi apabila semuanya berjalan lancar, tetapi juga tahu apa yang perlu dilakukan apabila pelayan menolak permintaan. Artikel ini membincangkan dua perkara yang paling kerap menyebabkan masalah dengan penyepaduan API Kencang.in: melebihi had kadar dan salah tafsir ralat.

Cara had kadar berfungsi

Had kadar mengehadkan jumlah permintaan seminit bagi setiap kunci API. Tujuannya untuk memastikan perkhidmatan stabil bagi semua pengguna. Had bergantung pada pelan: Pro mendapat 60 permintaan seminit, Business 300 seminit; butirannya di halaman harga. Kiraan ditetapkan semula setiap minit (tetingkap tetap), bukan tetingkap beralih.

Setiap respons menyertakan pengepala:

• X-RateLimit-Limit: had seminit untuk kunci anda.
• X-RateLimit-Remaining: baki permintaan pada minit berjalan.
• Retry-After: hanya pada respons 429, bilangan saat sebelum anda boleh mencuba lagi. Pengepala ini diseragamkan dalam MDN.

Strategi untuk mengelak daripada terkena 429

1. Pemprosesan berkelompok di pihak anda. Jika perlu membuat 500 pautan, jangan hantar semuanya serentak. Bariskan dan proses mengikut had, contohnya 50 seminit dengan jeda sekata.
2. Cache hasil. Data yang jarang berubah, seperti senarai domain atau butiran pautan, tidak perlu diminta berulang kali.
3. Gunakan titik akhir senarai dengan penomboran halaman bukannya memanggil butiran satu persatu.
4. Pantau X-RateLimit-Remaining dan perlahan secara proaktif apabila menghampiri sifar.

Mengendalikan 429 dengan exponential backoff

Apabila menerima 429, patuhi Retry-After. Jika pengepala tiada, gunakan exponential backoff: tunggu 1, 2, 4, 8 saat, ditambah jitter rawak supaya ramai klien tidak mencuba semula pada saat yang sama. Corak ini disarankan secara meluas, termasuk dalam Panduan cuba semula Google Cloud.

Kod ralat dan maksudnya

• 400 Permintaan Buruk: body bukan JSON yang sah atau parameter yang diperlukan tiada. Semak Content-Type dan struktur muatan.
• 401 Tanpa kebenaran: Kunci API tiada, salah atau telah dibatalkan. Jangan cuba semula; betulkan kunci.
• 403 Dilarang: ciri yang tidak disertakan dalam pelan anda, contohnya domain berjenama pada pelan Percuma, atau kuota pautan bulanan habis.
• 404 Tidak Ditemui: ID pautan tidak wujud atau bukan milik akaun anda.
• 429 Terlalu Banyak Permintaan: had kadar. Tunggu dan ulangi.
• 500/502/503: gangguan sementara pada pelayan. Cuba semula dengan backoff, maksimum beberapa kali, kemudian rekodkan untuk semakan.

Selain status HTTP, badan respons sentiasa mengandungi error dan message. Ralat pengesahan perniagaan, seperti "alias sudah digunakan" atau "URL disekat kerana berniat jahat", dikembalikan dengan status 200 dan error: 1. Jadi semak kedua-duanya. Semakan keselamatan URL diterangkan dalam artikel keselamatan pautan pendek.

Idempotensi dan pendua

Jika permintaan POST tamat masa pada rangkaian, anda tidak tahu sama ada pautan telah diwujudkan. Mengulangi ini boleh menghasilkan dua pautan. Penyelesaian: gunakan alias deterministik (cth. ID pesanan). Jika alias sudah wujud, API mengembalikan ralat "alias sudah digunakan" dan apl anda boleh mendapatkan semula pautan sedia ada melalui titik akhir carian dan bukannya membuat yang baharu.

Peloggan yang berguna

Rekodkan bagi setiap panggilan: titik akhir, status HTTP, nilai X-RateLimit-Remaining, dan message apabila ia gagal. Jangan log kunci API. Dengan log ini, anda boleh melihat corak, contohnya lonjakan 429 setiap 9 pagi apabila cron dijalankan, dan kemudian menyebarkan jadual.

Bilakah patut menaik taraf pelan?

Jika log menunjukkan anda kerap mencapai had walaupun sudah memproses secara berkelompok, itu tanda beban sebenar, bukannya pepijat. Pelan Business menyediakan 300 permintaan seminit dan pautan tanpa had. Untuk keperluan lebih tinggi, hubungi kami untuk pelan tersuai. Contoh kod asas untuk ketiga-tiga bahasa terdapat dalam artikel contoh kod API, dan dokumentasi lengkap di halaman pembangun.

Soalan lazim

Adakah had kadar dikira setiap akaun atau setiap kunci?

Setiap kunci API. Jika anda menggunakan berbilang penyepaduan, cipta kunci berasingan untuk setiap satu supaya satu penyepaduan yang sibuk tidak memakan kuota penyepaduan yang lain dan supaya pemantauan penggunaan lebih mudah dibaca dalam papan pemuka.

Adakah permintaan yang ditolak dengan 429 dikira?

Tidak. Permintaan yang ditolak kerana melebihi had tidak mengurangkan kuota minit berikutnya. Namun, menghantar permintaan berterusan ketika sudah dihadkan membazirkan sumber, jadi patuhi pengepala Retry-After.

Bagaimana untuk meningkatkan had permintaan?

Naik taraf kepada pelan Business untuk mendapatkan 300 permintaan seminit. Untuk keperluan di atas itu, seperti penyepaduan dengan berjuta-juta pautan, hubungi kami untuk mendapatkan pelan tersuai dengan had tersuai.

Adakah ralat 5xx bermakna pautan saya hilang?

Tidak. Ralat 5xx menunjukkan gangguan sementara semasa memproses permintaan, bukannya kehilangan data. Cuba semula dengan backoff; jika gangguan berterusan lebih daripada beberapa minit, semak halaman status atau hubungi kami.