Struktur respons dan kode kesalahan HappyOyster Open API, termasuk kode bisnis, skenario umum, dan saran penanganan.
Dokumen ini menjelaskan struktur respons dan kode kesalahan dari HappyOyster Open API. Dokumen ini berlaku untuk semua endpoint Open API dari model Adventure, Directing, dan Acting.
Setelah permintaan lolos autentikasi gateway (baik untuk keberhasilan bisnis maupun kesalahan bisnis), respons selalu mengembalikan HTTP 200 dengan struktur JSON berikut sebagai body:
Kegagalan lapisan gateway seperti verifikasi AK, tanda tangan, atau stempel waktu ditolak secara langsung, sehingga respons tersebut tidak mengikuti struktur ini dan biasanya dikembalikan dengan kode status HTTP 4xx / 5xx — lihat Kode kesalahan.
Akses lintas model tidak mengungkapkan apakah sumber daya ada: endpoint World mengembalikan
Saat melakukan kueri status Travel atau daftar Travel, item dengan
Setiap
Struktur respons
Setelah permintaan lolos autentikasi gateway (baik untuk keberhasilan bisnis maupun kesalahan bisnis), respons selalu mengembalikan HTTP 200 dengan struktur JSON berikut sebagai body:
| Field | Tipe | Deskripsi |
|---|---|---|
code | integer | Kode pengembalian bisnis. 0 berarti berhasil; nilai non-0 berarti terjadi kesalahan bisnis — lihat daftar kode kesalahan di bawah ini. |
message | string | null | Pesan kesalahan yang dapat dibaca manusia. null ketika code=0. |
data | object | null | Payload bisnis. Jika berhasil, berisi objek respons khusus endpoint; jika terjadi kesalahan, biasanya null. |
Daftar kode kesalahan
| kode | Deskripsi | Skenario umum & penanganan |
|---|---|---|
0 | Success | Permintaan berhasil; baca data. |
400000 | Parameter permintaan tidak valid | mode tidak cocok dengan model saat ini; prompt atau firstFrameImage hilang; prompt terlalu panjang; creationModel / uploadMode / resolution / aspectRatio / perspective memiliki nilai yang tidak sah; format gambar atau ID terenkripsi tidak valid. Perbaiki parameter sesuai dokumen API dan coba lagi. |
400001 | Gagal mengambil atau menyimpan URL gambar | URL gambar bingkai pertama atau referensi tidak dapat diakses atau telah kedaluwarsa. Verifikasi aksesibilitas dan validitas URL, lalu coba lagi membuat World. |
401010 | ticket tidak valid atau kedaluwarsa | Masuk travel (enter-travel). Panggil get-travel-credential lagi untuk mendapatkan ticket. |
401011 | ticket sudah digunakan | Masuk travel. ticket bersifat sekali pakai; dapatkan yang baru. |
403001 | World tidak ada, telah dihapus, bukan milik Anda, atau bukan milik model saat ini | Kueri, pertukaran kredensial, enter travel, dan pemfilteran daftar. Pada penghapusan, kode ini dikembalikan hanya untuk ID lintas akun, lintas ruang kerja, atau lintas model; ID yang sudah tidak ada di bawah akun yang sama mengembalikan code=0, deleted=false. |
403002 | World tidak ready atau tidak tersedia | Pertukaran kredensial, masuk travel. Poll status build hingga ready sebelum beroperasi. |
403003 | Endpoint ini hanya mengizinkan API Key utama | Manajemen World, daftar Travel, artefak, dll. Panggil dengan API Key utama (dimulai dengan sk-). |
403004 | Konten input gagal melewati kebijakan keamanan konten | Buat World, kirim instruct. Sesuaikan konten teks dan coba lagi. |
403005 | Gambar input gagal verifikasi hak cipta atau IP | Buat World. Ganti dengan gambar yang sesuai dan coba lagi. |
403007 | Kuota fitur atau layanan tidak diaktifkan | Buat, pertukaran kredensial, masuk travel. Confirm kemampuan model yang sesuai telah diaktifkan. |
403008 | Konfigurasi kapasitas sementara tidak tersedia | Buat, pertukaran kredensial, enter travel. Coba lagi nanti atau hubungi penyedia layanan untuk meningkatkan skala. |
404000 | Travel tidak ada, bukan milik Anda, bukan milik model saat ini, atau tidak memiliki artefak yang tersedia | Kueri status Travel, kontrol, akhiri, kueri artefak. |
409000 | Permintaan bertentangan dengan status sumber daya saat ini | Endpoint kontrol seperti jeda, lanjutkan, akhiri, dan instruct; juga dikembalikan saat memanggil endpoint yang tidak didukung oleh model. |
429001 | Konkurensi untuk spesifikasi saat ini penuh | Enter travel. Coba lagi nanti atau tingkatkan spesifikasi konkurensi. |
429002 | Kapasitas tersedia tidak mencukupi | Masuk travel. Coba lagi nanti. |
500000 | Kesalahan sistem internal | Pengecualian yang tidak terklasifikasi; juga dapat dikembalikan saat memanggil endpoint yang tidak didukung (misalnya, rewind pada beberapa model). |
500001 | Gagal mengalokasikan sumber daya streaming | Masuk travel. Coba lagi nanti. |
code=403001 dan endpoint Travel mengembalikan code=404000.
errorCode kegagalan Travel
Saat melakukan kueri status Travel atau daftar Travel, item dengan status=failed juga membawa bidang terstruktur errorCode dan deskripsi bahasa Inggris errorMessage (lihat dokumen API terkait untuk struktur respons kegagalan). Teks errorMessage untuk errorCode yang sama mungkin berbeda antara endpoint kueri dan respons End Travel; lakukan percabangan berdasarkan errorCode, bukan berdasarkan errorMessage.
| errorCode | errorMessage | Deskripsi |
|---|---|---|
TRAVEL_SESSION_INIT_FAILED | Failed to allocate inference resources. | Sesi inferensi gagal diinisialisasi saat memasuki travel, biasanya karena sumber daya inferensi yang tidak mencukupi |
TRAVEL_NO_STREAM_AUTO_END | No video stream was received before timeout. | Klien tidak menerima stream sebelum batas waktu; akhiri Travel dengan meneruskan failCode dalam permintaan End Travel |
TRAVEL_STREAM_CREATE_FAILED | Failed to create the video stream. | Gagal membuat channel streaming |
CONTENT_VIDEO_MODERATION_REJECTED | Something went wrong. | Gambar pengalaman terganggu oleh kebijakan keamanan konten |
TRAVEL_RUNTIME_FAILED | The experience was interrupted by a runtime error. | Kegagalan runtime lainnya, atau server tidak mencatat alasan spesifik |
errorCode yang tidak tercantum dapat dianggap sebagai kegagalan yang tidak diketahui.