Penjelasan Kode Error API Text-to-Video

Sebagian besar kegagalan API text-to-video bermuara pada 5 kelompok: request yang salah, masalah autentikasi, batas rate, blokir keamanan, atau masalah server. Jika saya memeriksa status HTTP, isi error lengkap, request atau task ID, dan waktu kegagalan, biasanya saya bisa menemukan penyebabnya dengan cepat.

Berikut versi singkatnya:

• Error seri 400 biasanya berarti saya perlu memperbaiki request.
• 401/403 biasanya menunjuk ke API key, akses, penagihan, atau aturan IP.
• 429 berarti saya mencapai batas request, job, atau pengeluaran.
• 200 OK saat submit tidak berarti video selesai. Saya tetap perlu melakukan polling pada job dan memeriksa failed.
• Error seri 500 sering butuh retry, tetapi hanya setelah saya memeriksa apakah job masih berjalan.
• Blokir keamanan bisa terjadi sebelum, selama, atau setelah generasi, dan beberapa API mungkin mengembalikan lebih sedikit klip daripada menggagalkan seluruh job.

Beberapa angka menonjol. Job video, seperti yang menggunakan Sora 2, dapat menahan GPU selama 30–90 detik, timeout klien mungkin perlu 10+ menit, dan rencana retry yang umum adalah mulai dari 5 detik, batasi di 60 detik, berhenti setelah 3 percobaan.

Jika saya ingin lebih sedikit job yang gagal dan lebih sedikit biaya ganda, saya menjaga alur kerja tetap sederhana:

• Catat isi error dan task ID
• Pisahkan error lapisan API dari kegagalan tingkat job
• Retry hanya untuk kasus 429 dan 5xx
• Periksa state task sebelum saya submit job yang sama lagi
• Sematkan versi model persis alih-alih memakai alias seperti latest

Pesan Error API untuk Pengalaman Developer yang BAIK

Perbandingan Cepat

Singkatnya: keberhasilan submission bukanlah keberhasilan render. Saya akan memperlakukan hasil polling sebagai sumber kebenaran dan menggunakan payload error - bukan hanya kode status - untuk memutuskan langkah berikutnya.

Error request sisi klien: kode seri 400 yang bisa Anda perbaiki

Setelah Anda mencatat detail error, langkah berikutnya adalah mencari tahu apa yang salah di sisi request. Mulai dari isi error, lalu petakan kode HTTP ke perbaikannya.

400, 404, 413, dan 415: arti setiap kode untuk request video

Setiap kode menunjuk ke jenis kesalahan request yang berbeda. Sebuah 400 biasanya berarti JSON rusak, field wajib hilang, atau tipe parameter tidak valid. Misalnya, memasukkan duration sebagai string ("6") alih-alih integer (6) akan gagal validasi ^[4]. Sebuah 404 berarti model ID atau path endpoint salah, sering karena typo kecil seperti wan2.7 alih-alih [wan-2.7](https://apimart.ai/ja/model/wan-2-7) atau [wan-2.6](https://apimart.ai/model/wan-2-6) ^[7]. Sebuah 413 muncul ketika gambar atau video referensi lebih besar dari batas ukuran unggahan ^[4][7]. Sebuah 415 berarti header Content-Type salah, atau format file tidak didukung oleh model ^[5].

Ketidakcocokan model dan parameter yang menyebabkan kegagalan validasi

Bahkan ketika JSON Anda bersih, request masih bisa gagal validasi karena model tidak semuanya mengikuti aturan yang sama. Resolusi, durasi, rasio aspek, dan batas aset dapat berbeda dari satu model ke model lainnya.

Ambil MiniMax-Hailuo-2.3. Ia mendukung 10 detik pada 768p, tetapi jika Anda meminta 1080p, durasi maksimum turun menjadi 6 detik ^[6]. Aturan aset bisa sama ketatnya. Kling 3.0 mengharuskan gambar input minimal 300 px di kedua dimensi, dengan rasio aspek antara 1:2.5 dan 2.5:1. Wan 2.7 mengharuskan video referensi berdurasi 2–10 detik dan tidak lebih besar dari 100 MB ^[4][7].

Sebuah 422 biasanya berarti parameter Anda saling bertabrakan. Misalnya, SkyReels V4 mengembalikan 422 ketika Anda menggabungkan field Image-to-Video dan Omni dalam request yang sama ^[8].

Satu kebiasaan kecil bisa menghemat banyak waktu: gunakan string versi yang disematkan alih-alih alias generik. Aturan parameter bisa berubah antar versi model ^[3]. Jika validasi masih gagal, periksa batas persis model sebelum Anda retry.

Jika request tervalidasi tetapi masih gagal, lanjut ke autentikasi, batas rate, dan pemeriksaan keamanan.

Autentikasi, izin, dan batas rate

Setelah validasi lolos, sebagian besar kegagalan yang tersisa bermuara pada tiga hal: auth, izin, atau batas rate.

401 dan 403: error API key dan akses

Sebuah error 401 Unauthorized berarti request tidak menyertakan kredensial autentikasi yang valid. Penyebab umumnya adalah API key hilang, key tidak valid, key yang dinonaktifkan atau dihapus, atau header Authorization yang rusak ^[9][1][2].

Banyak API mengharapkan:

Authorization: Bearer YOUR_API_KEY

Beberapa platform menggunakan x-api-key sebagai gantinya. Jadi jika nama atau format header salah, hal itu saja bisa memicu 401 ^[1][10].

Mulai dari hal dasar. Periksa variabel lingkungan, pastikan key masih aktif, dan konfirmasi setup CI/CD Anda menyuntikkan secret dengan benar di setiap lingkungan ^[3]. Membaca isi respons alih-alih berhenti di kode status HTTP juga membantu. Error seperti invalid_api_key, token_expired, atau account_banned biasanya memberi tahu Anda apa yang rusak jauh lebih cepat ^[9][3].

Sebuah 403 Forbidden berarti server mengenali Anda, tetapi tetap memblokir request. Itu biasanya menunjuk ke masalah akses. Key Anda mungkin tidak memiliki scope model yang tepat, paket akun Anda mungkin tidak menyertakan endpoint itu, kredit Anda mungkin habis, atau IP request Anda mungkin tidak ada di allowlist ^[3][9].

Isi respons juga penting di sini. Jika Anda melihat insufficient_credits, periksa penagihan. Jika Anda melihat permission_error, periksa scope, akses model, atau batas paket. Dan jika akses tampak baik-baik saja tetapi trafik terlalu tinggi, perhentian berikutnya biasanya 429.

429: error batas rate dan kuota terlampaui

Jika auth berhasil, volume request sering menjadi titik hambatan berikutnya. Sebuah error 429 Too Many Requests berarti Anda mencapai throttle, batas konkurensi, atau batas pengeluaran ^[3][9][10]. Dalam bahasa sederhana: Anda mengirim terlalu banyak request dalam jendela waktu singkat, menjalankan terlalu banyak job sekaligus, atau melewati batas penagihan ^[3][9].

Sekali lagi, isi respons memberi Anda petunjuk terbaik. rate_limit_exceeded biasanya berarti Anda harus menggunakan exponential backoff. spend_limit_exceeded berarti sudah waktunya memeriksa pengaturan penagihan ^[3][9].

Antrekan batch job secara lokal jika Anda bisa, dan awasi header-header ini ^[2]:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Jika Anda menggunakan APIMart, satu key untuk semua model dapat mengurangi pergeseran auth ^[3]. Bahkan begitu, alur debugging tetap kurang lebih sama: baca isi respons, verifikasi variabel lingkungan Anda, dan pastikan akun dapat mengakses model yang Anda panggil.

Blokir keamanan, timeout, dan kegagalan sisi server

Setelah validasi request dan auth lolos, kegagalan yang tersisa biasanya jatuh ke dua kelompok: blokir moderasi dan masalah sisi server. Jadi begitu auth, kuota, dan validasi sudah teratasi, pecah sisa debugging Anda ke dua jalur itu.

Error moderasi dan kebijakan konten dalam generasi video

Blokir keamanan bisa terjadi di tiga titik berbeda: sebelum generasi dimulai (request ditolak seketika), selama rendering (job dihentikan di tengah jalan), atau setelah video diproduksi (output difilter sebelum dikirim) ^[11]. Kasus terakhir itu membuat orang tersandung. Sebuah job bisa selesai dan tetap tidak mengirim apa-apa jika hasilnya difilter.

Dengan API berbasis polling, status HTTP bisa menyesatkan. Anda mungkin mendapat 200 OK dari pemeriksaan status, sementara isi JSON menyatakan state: "failed" dan menyertakan error seperti SensitiveContentDetected atau NSFW ^[12]. Dalam praktiknya, isi polling adalah sumber kebenaran, bukan kode status HTTP.

Jika blokir moderasi menyala, jangan retry prompt yang sama persis. Tulis ulang. Kata-kata sinematografi yang lugas dan teknis bisa membantu mengurangi false positive dari filter keamanan yang ketat ^[11]. Misalnya:

• gimbal shot
• medium tracking shot
• golden hour lighting

Ada seluk-beluk lain di sini. Beberapa model, termasuk Google Veo, mungkin mengembalikan lebih sedikit klip daripada yang Anda minta ketika sebagian output diblokir oleh filter keamanan, alih-alih menggagalkan seluruh job ^[3]. Jadi jangan hanya memeriksa apakah request selesai. Periksa bahwa jumlah aset yang dikembalikan cocok dengan jumlah yang Anda minta.

Jika prompt tampak bersih dan job masih gagal, lanjut ke lapisan berikutnya: stabilitas server.

500, 502, 503, dan error timeout untuk job video async

Kegagalan sisi server berada di bagian berbeda dari alur debugging. Job text-to-video sering menahan slot GPU selama 30–90 detik ^[3], yang membuatnya lebih sensitif terhadap kelebihan beban dan timeout.

Untuk error 500 dan 504, periksa status job sebelum Anda retry. Retry buta bisa menciptakan render duplikat dan menggandakan biaya Anda ^[3]. Catat setiap taskId atau prediction_id agar Anda bisa mengueri endpoint status langsung sebelum submit job baru ^[3][13].

Ketika retry aman, gunakan exponential backoff dengan jitter. Setup praktisnya adalah:

• mulai dari 5 detik
• batasi di 60 detik
• berhenti setelah 3 percobaan ^[13][12]

Setel timeout klien ke 10 menit atau lebih ^[3], dan pasang alert pada nilai predict_time yang meningkat ^[3].

Alur kerja debugging langkah demi langkah untuk API text-to-video

Klasifikasikan error, lalu terapkan perbaikan yang tepat

Gunakan alur kerja ini untuk beranjak dari gejala ke perbaikan dalam satu langkah. Pertama, baca isi respons lengkap. Lalu sortir kegagalan berdasarkan kode status HTTP dan apa yang dikatakan isi error. Beberapa penyedia juga mengirim rentang error internal, tetapi panduan utama Anda seharusnya kode status HTTP dan isi error ^[3][1].

Mulai dari isi respons, lalu tempatkan hasilnya ke salah satu kelompok ini:

Begitu sebuah job disubmit, berhentilah berpikir hanya dalam hal respons HTTP dan lihat juga state task. Untuk job async, periksa respons polling untuk failed atau expired sebelum Anda kirim job yang sama lagi. Satu langkah itu bisa menyelamatkan Anda dari biaya ekstra dan banyak kebingungan.

Sebelum Anda menyentuh kode, periksa halaman status penyedia. Jika layanan sedang terdegradasi, debugging lokal tidak akan banyak memberi tahu Anda. Setelah itu, periksa header respons x-deny-reason. Penolakan tingkat proxy bisa tampak seperti error model jika Anda melewatkan pemeriksaan itu ^[3].

Juga, sematkan string versi model persis seperti kling-v3.0-std alih-alih latest. Pembaruan model diam-diam bisa memperkenalkan kegagalan validasi baru ke dalam pipeline yang berjalan baik sehari sebelumnya ^[3].

Poin utama untuk integrasi yang lebih andal

Sebagian besar kegagalan API text-to-video mengikuti beberapa pola yang berulang. Jika Anda mendapat error 4xx, Anda perlu mengubah request, kredensial, atau setup. Mengirim panggilan yang sama lagi biasanya tidak akan memperbaiki apa pun.

• Catat input request: model ID, hash prompt, dan parameter (lihat tutorial AI API kami untuk praktik terbaik logging).
• Catat task ID, status akhir, predict_time, dan pesan error lengkap.
• Retry hanya 429 dan 5xx setelah memeriksa state task untuk menghindari render duplikat dan biaya ganda ^[3].
• Awasi predict_time untuk lonjakan - itu bisa menandakan degradasi infrastruktur lebih awal ^[3].

FAQ

Bagaimana saya tahu apakah sebuah job video benar-benar gagal?

Lakukan polling ke endpoint status task dengan task ID yang Anda dapat saat submit job. Jika field status kembali sebagai failed, job tidak berhasil.

Berikutnya, lihat field error dalam respons. Itu memberi tahu Anda mengapa gagal, sehingga Anda bisa memutuskan langkah berikutnya:

• sesuaikan prompt Anda
• periksa saldo akun Anda
• tunggu jika ada masalah infrastruktur

Anda juga bisa menggunakan webhook untuk mendapat notifikasi otomatis ketika sebuah job masuk ke state failed.

Kapan saya harus retry request API text-to-video?

Retry error transien seperti batas rate 429 dan masalah sisi server 500 dengan exponential backoff. Itu memperlambat percobaan ulang dan membantu Anda menghindari menghantam sistem.

Untuk 504 Gateway Timeout atau kegagalan task, periksa status task sebelum Anda coba lagi. Retry buta bisa memicu render duplikat dan menambah biaya.

Jangan retry error 400 atau 401. Itu biasanya berarti request itu sendiri perlu diperbaiki dulu.

Mengapa sebuah prompt bisa diblokir setelah submission?

Sebuah prompt biasanya diblokir karena melanggar aturan keamanan atau moderasi penyedia. Itu bisa terjadi tepat saat Anda submit, atau kemudian selama generasi jika sistem mendeteksi konten visual atau audio yang dilarang.

Pemicu umum termasuk topik sensitif, kekerasan, anak di bawah umur, atau materi berhak cipta. Dan karena sistem moderasi cenderung berhati-hati, bahkan prompt yang tidak berbahaya bisa ditandai.

Jika itu terjadi, tulis ulang request dalam bahasa yang lebih netral dan deskriptif.