WaveSpeedAI

Autentikasi API WaveSpeed & Penanganan Error: Perbaiki 401, 429, 5xx Seperti Profesional

Autentikasi API WaveSpeed & Penanganan Error: Perbaiki 401, 429, 5xx Seperti Profesional

Halo, saya Dora—saya memecahkan API agar Anda tidak perlu.

Minggu lalu saya terus mendapat error 401. Bukan yang misterius—yang bodoh, di mana Anda tahu ada yang salah tapi tidak bisa melihatnya. Ternyata saya telah menggunakan X-API-Key di header saya. WaveSpeed menginginkan Authorization: Bearer. Perbedaan kecil. Dua jam terbuang.

Itulah masalahnya dengan autentikasi API—ini berjalan diam-diam saat benar, dan gagal keras saat tidak. Dan WaveSpeed, seperti sebagian besar API modern, tidak memberi Anda banyak ruang gerak. Itulah yang saya pelajari dari menggunakan API WaveSpeed untuk pembuatan gambar dan video selama beberapa bulan terakhir—dan apa yang benar-benar membantu saat segalanya rusak.

Cara Autentikasi API WaveSpeed Sebenarnya Bekerja

WaveSpeed menggunakan autentikasi Bearer token. Setiap permintaan membutuhkan:

  • Authorization: Bearer <YOUR_API_KEY>
  • Content-Type: application/json

Formatnya sangat sederhana:

Authorization: Bearer your_api_key_here
Content-Type: application/json

Saya telah melihat orang mencoba X-API-Key, Api-Key, atau membungkusnya dalam tanda kutip. Dokumentasi resmi WaveSpeed dan contoh secara konsisten menunjukkan format Bearer token. Itu saja. Tidak ada variasi.

Mendapatkan API Key Anda

API key Anda berada di dashboard WaveSpeed di wavespeed.ai/accesskey. Anda perlu mengisi ulang akun Anda sebelum Anda dapat membuat yang baru—tidak ada kunci untuk pengguna tier gratis. Saat Anda menyalin kunci, perhatikan spasi tambahan. Saya telah melakukannya dua kali—menangkap spasi di akhir dan menghabiskan 20 menit untuk debug sebelum saya menyadarinya.

Alur Autentikasi untuk API WaveSpeed

Tidak ada refresh token, tidak ada OAuth, tidak ada langkah perantara. Anda mengirim Bearer token, WaveSpeed memvalidasinya, permintaan Anda либо melanjutkan либо ditolak dengan 401. Jika autentikasi gagal, Anda akan mendapatkan respons 401 segera. Error biasanya mengatakan “invalid authentication” dan menyuruh Anda memverifikasi kunci Anda.

Menangani Error 401 Unauthorized

A 401 dari WaveSpeed berarti itu melihat header Authorization Anda dan berkata “Saya tidak mengenali ini.”

Daftar penyebab umum

Tersangka biasanya:

  • Format header yang salah (tidak menggunakan Authorization: Bearer)
  • API key disalin dengan spasi trailing atau line break
  • Kunci diregenerasi di dashboard tetapi kunci lama masih ada di kode
  • Variabel lingkungan tidak memuat
  • Tidak ada top-up akun—kunci tidak akan dihasilkan tanpa menambahkan kredit terlebih dahulu

Perbaikan Cepat

Saat saya terkena 401, saya mulai dari sini: Pertama, catat header yang tepat. Bukan apa yang saya pikir saya kirim—apa yang sebenarnya ada dalam permintaan HTTP. Sering kali Bearer token tidak terbentuk dengan baik atau nama header sedikit berbeda. Kedua, salin kunci segar dari dashboard. Uji segera dengan curl sebelum memasukkannya ke dalam kode:

curl -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-dev" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "test"}'

Jika curl bekerja, masalahnya ada di kode aplikasi saya. Jika curl gagal, kuncinya sendiri salah. Ketiga, periksa saldo akun. WaveSpeed beroperasi pada model berbasis kredit—jika saldo Anda mencapai nol, panggilan API mungkin gagal.

Mengelola Respons 429 Rate Limit

Batas kecepatan WaveSpeed berjenjang: Bronze (batas dasar, top-up $100), Silver (konkursi lebih tinggi, top-up $1.000), dan Gold (kustom, $10.000+). Setiap tier memiliki batas throughput dan tugas konkuren yang berbeda.

Spesifikasinya tidak didokumentasikan secara publik dalam angka yang tepat, tetapi polanya jelas: mengirim terlalu banyak permintaan terlalu cepat, dapatkan 429.

Memahami Batas Kecepatan

Menurut FAQ, batas contoh termasuk Bronze di 10 gambar / 5 video per menit dengan maksimal 3 tugas konkuren, Silver di 500 gambar / 60 video per menit dengan maksimal 100 konkuren, dan **Gold di 2000 gambar / 120 video per menit dengan maksimal 200 konkuren.

Jika Anda mendapatkan error “Too Many Requests”, Anda mungkin mencapai batas tier Anda. Untuk mencegah throttling, pertimbangkan untuk meningkatkan paket Anda.

Strategi exponential backoff untuk retry

Saat saya terkena 429, saya tunggu sebelum mencoba lagi. Bukan segera—itu hanya membuat saya mendapatkan 429 lagi. Saya menggunakan exponential backoff:

  • Percobaan pertama: tunggu 1 detik
  • Percobaan kedua: tunggu 2 detik
  • Percobaan ketiga: tunggu 4 detik
  • Setelah tiga percobaan, berhenti dan catat kegagalannya

Banyak API menyertakan header Retry-After yang memberi tahu Anda dengan tepat berapa lama untuk menunggu. Periksa dan gunakan nilai itu jika tersedia.

Merancang antrean permintaan sisi klien

Untuk operasi massal—seperti menghasilkan 100 gambar dalam pekerjaan batch—saya menambahkan antrean yang menghormati batas tier saya:

  • Lacak berapa banyak permintaan yang telah saya kirim dalam jendela waktu saat ini
  • Setelah saya mendekati batas (katakan, 90% throughput tier saya), jeda permintaan baru
  • Lanjutkan saat jendela waktu berakhir

Ini mencegah sebagian besar 429 sebelum terjadi. Saya masih menemukannya kadang-kadang saat beberapa proses berjalan bersamaan, tetapi logika retry menangani yang itu.

Menangani Error 5xx Server

Error server berbeda. Sebuah 401 atau 429 adalah saya melakukan sesuatu yang salah. A 500 atau 503 dari WaveSpeed berarti sesuatu rusak di pihak mereka.

Pola Retry Aman

Untuk error 5xx, aman untuk mencoba lagi—sebagian besar error server diselesaikan dalam beberapa detik. Pola yang baik dari dokumentasi Microsoft adalah untuk mencoba ulang segera sekali jika kesalahan transien, kemudian kembali ke exponential backoff jika persisten.

Pendekatan saya:

  • Coba ulang segera sekali (mungkin itu hanya gangguan)
  • Jika itu gagal, gunakan exponential backoff yang sama seperti 429
  • Batas di tiga retry total
  • Catat kegagalannya dan lanjutkan

Untuk permintaan GET (memeriksa status pembuatan), retry selalu aman. Untuk permintaan POST (memulai pembuatan baru), saya lebih hati-hati—saya tidak ingin secara tidak sengaja memulai pekerjaan yang sama dua kali.

Mengonfigurasi timeout secara efektif

Saya menetapkan dua timeout:

  • Connection timeout: 5 detik
  • Read timeout: 30 detik

WaveSpeed menargetkan “kurang dari 2 detik” untuk gambar dan “sekitar 2 menit” untuk video, meskipun waktu sebenarnya tergantung pada model, resolusi, dan beban.

Sebagian besar pembuatan gambar selesai dalam kurang dari 5 detik. Video memakan waktu lebih lama—kadang-kadang 60–90 detik. Tetapi saya telah melihat lonjakan sesekali ke 20+ detik bahkan untuk gambar.

Tanpa timeout, permintaan yang lambat bisa hang tanpa batas. Dengannya, saya mendapatkan error yang bersih dan dapat mencoba lagi.

Logging & Observability di API WaveSpeed

Setelah autentikasi dan penanganan error bekerja, saya perlu tahu mereka tetap bekerja.

Apa yang Harus Dicatat

Untuk setiap panggilan API WaveSpeed, saya catat:

  • Endpoint model yang dipanggil
  • Kode status HTTP
  • Waktu respons dalam milidetik
  • Apakah itu adalah retry, dan nomor percobaan mana

Saat menghubungi dukungan WaveSpeed tentang permintaan yang gagal, mereka meminta ID pekerjaan dan timestamp. Simpan ini dalam log Anda untuk debug.

Ambang Peringatan

Saya menetapkan peringatan untuk:

  • 401 error rate di atas 1% (autentikasi rusak)
  • 429 error rate di atas 5% (mencapai batas kecepatan secara konsisten)
  • Setiap error 5xx (harus jarang terjadi)
  • Waktu respons rata-rata di atas 10 detik (masalah kinerja potensial)

Ini bukan ambang universal—mereka adalah yang masuk akal untuk penggunaan saya. Yang penting adalah memiliki ambang tertentu yang memicu investigasi sebelum pengguna menyadarinya.

Daftar Periksa Produksi Autentikasi API WaveSpeed

Sebelum go live:

  • API key disimpan dalam variabel lingkungan, bukan kode
  • Menggunakan format Authorization: Bearer dengan benar
  • Header Content-Type diatur ke application/json
  • Logika retry dengan exponential backoff untuk 429 dan 5xx
  • Timeout dikonfigurasi (koneksi 5 detik, baca 30 detik)
  • Logging mencakup kode status, waktu respons, ID pekerjaan
  • Alert diatur untuk lonjakan tingkat error
  • Rate limiting sisi klien untuk tetap dalam batas tier
  • Pemantauan keseimbangan terintegrasi untuk melacak penggunaan kredit

Saya masih mendapatkan 429 kadang-kadang selama lonjakan traffic. Dan saya melihat beberapa error 5xx saat WaveSpeed mengalami masalah singkat bulan lalu. Tetapi dengan penyetelan ini, error itu tidak berkaskade.

Autentikasi sebagian besar bekerja dengan hanya bekerja. Usaha dilakukan dalam menangani waktu itu tidak—dengan bersih, dapat diprediksi, tanpa membangunkan saya pada pukul 2 pagi karena saldo kredit mencapai nol.

💡 Menghadapi masalah? Posting kode error + ID permintaan di komentar, dan kami akan memandu Anda melalui daftar periksa troubleshooting untuk membantu mengidentifikasi akar penyebabnya.

**Tip: Sebagian besar error adalah sisi klien dan dapat dikontrol (header, API key, batas kecepatan), tetapi proses ini juga membantu Anda menemukan masalah yang membutuhkan dukungan WaveSpeed.