status: "failed". Job yang gagal dan dibatalkan tidak ditagih. Anda hanya membayar untuk job yang selesai. Pada node app, job milik app itu sendiri tidak pernah ditagih. Setiap node generasi atau LLM dikenai biaya saat job miliknya sendiri selesai. Kegagalan tidak membatalkan node paralel atau cabang lain, sehingga node yang selesai setelah app sudah gagal tetap dikenai biaya, dan biaya tersebut tidak dikembalikan. Node yang gagal, dibatalkan, atau tidak pernah dimulai tidak dikenai biaya. Lihat API Keys & Billing.
Error saat permintaan dan job yang gagal
Error saat permintaan mengembalikan status4xx atau 5xx. Tidak ada job yang dibuat. Baca body seperti yang dijelaskan di bawah.
Job yang gagal mengembalikan status sukses saat dikirim. Lakukan polling GET /jobs/{id} atau tunggu webhook. Saat job selesai, status bernilai "failed" dan kegagalannya ada di objek error tingkat atas. Jangan membaca result pada job yang gagal: field tersebut dihilangkan (atau null). Field ini hanya berisi output saat status bernilai "completed". Job cancelled tidak memiliki result maupun error.
Buat percabangan berdasarkan error.code. message dapat dihilangkan, dan untuk provider_error serta internal, isinya adalah teks bebas dari provider. Jangan mem-parsing message.
Body respons
Pada generate, jobs, assets, styles, dan node apps, bacamessage ?? error saat body berupa JSON. Salah satu dari kedua field tersebut membawa ringkasannya. Beberapa body 5xx bukan JSON, termasuk 502 yang body-nya berupa teks biasa error code: 502. Lakukan parsing secara defensif: jika body bukan JSON, buat percabangan berdasarkan status HTTP.
Sebagian besar kegagalan menggunakan { "message": "..." }, terkadang dengan field tambahan (limit, jobType, modelAccessDenial). JSON tidak valid dan beberapa handler di bawah menggunakan { "error": "..." } sebagai gantinya.
Endpoint MCP seperti /mcp mengembalikan error JSON-RPC, { "jsonrpc", "id", "error": { "code", "message" } }, bukan body HTTP di halaman ini.
Kirim Accept: application/json
Error { "message" }, termasuk 401 dan 404, berupa JSON saat Accept bernilai application/json atau */*. Saat Accept tidak ada, atau bernilai text/html, status tersebut berupa halaman HTML (Content-Type: text/html) dan parser JSON akan gagal.
Hal ini penting untuk klien yang tidak mengirim header Accept. urllib milik Python adalah salah satunya. curl mengirim Accept: */* secara default, begitu pula fetch milik Node, sehingga keduanya menerima JSON kecuali Anda menimpa Accept.
POST /generate/..., GET /jobs/{id}, GET /styles, dan GET /assets tanpa autentikasi mengembalikan 401 {"message":"Unauthorized"} untuk */* dan application/json, serta halaman HTML untuk Accept yang tidak ada atau text/html. GET /jobs/{id} yang terautentikasi untuk id yang tidak dikenal berperilaku sama dengan statusnya: 404 JSON {"message":"Job not found or unauthorized"} saat Accept meminta JSON, dan 404 text/html saat Accept tidak ada.
JSON tidak valid (400) dan validasi (422) menggunakan { "error" } dan tetap berupa JSON meskipun Accept tidak ada. Hal yang sama berlaku untuk 422 field yang dihapus, 410 sunset, 402 Zero Data Retention, respons { "error" } node-app, dan error Agent operation API yang dipetakan. 402 dan 429 saat menerima job POST /generate/... juga berupa JSON, termasuk untuk Accept dari browser.
413 dan 500 menggunakan { "message" } dan mengikuti Accept, seperti 401 dan 404.
Validasi (422)
details mencantumkan setiap masalah. field adalah path yang digabungkan dengan . ("image_style_references.0.url"). Error tingkat objek menggunakan string kosong, seperti pada key tidak dikenal di atas. Beberapa key tidak dikenal menghasilkan Unrecognized keys: ... dengan field kosong yang sama. expected hanya ditambahkan saat code bernilai "invalid_type".
Header X-Webhook-URL yang tidak valid menggunakan 422 yang sama.
GET /jobs dengan parameter query yang tidak valid juga mengembalikan 422 ini. Bukan 400.
Pemeriksaan input Zero Data Retention yang gagal di dalam tool mengembalikan 422 dengan penjelasan di message (bentuk { "message" }, sehingga Accept berpengaruh). Lihat Zero Data Retention.
Field yang dihapus dan deprecated (422)
Field batchSize / batch_size yang telah dihapus menggunakan 422 yang berbeda. Tidak ada array details:
batch_size dihapus dengan cara yang sama. field berisi nama mana pun yang Anda kirim.
Alias field yang deprecated menggunakan reason "deprecated_field" atau "conflicting_fields", ditambah replacement, sunset_date, dan migration_url jika relevan. Buat percabangan berdasarkan error dan reason. Kalimat yang ditampilkan kepada pengguna adalah message.
Model sunset (410)
Model yang telah melewati tanggal sunset-nya mengembalikan 410 dengan Deprecation: true dan header Sunset (tanggal RFC 1123):
error adalah nilai stabil "model_unavailable". replacement dan migration_url dihilangkan saat tidak ada pengganti yang direkomendasikan. Mengulang model yang sama akan terus mengembalikan 410. Beralihlah ke replacement jika tersedia, dan lihat Deprecations.
Model yang deprecated tetapi masih aktif mengirim Deprecation dan Sunset di setiap respons, termasuk error. Menggunakan alias field yang deprecated juga demikian, termasuk pada 422 miliknya sendiri. Saat panduan migrasi tersedia, header Link: <migration_url>; rel="deprecation" juga dikirim.
Kode status
400
JSON tidak valid pada generate selalu berupa JSON, tanpa memerlukan header Accept:
{ "error" } untuk URL input yang tidak dapat digunakannya: Invalid URL for input "<key>", atau Failed to download URL for <key>: …. Pesan unduhan ini juga mencakup kegagalan sementara, sehingga tidak seperti generate (lihat Unduhan input), kegagalan unduhan node-app selalu 400. Lakukan retry sekali jika URL-nya valid.
JSON tidak valid pada POST /node-apps/{id}/execute bukan 400 generate di atas. Hasilnya menjadi 500 { "message": "Internal Error" }, tanpa teks exception, dan mengikuti Accept.
Respons 400 lainnya pada assets dan node apps berupa { "message": "..." } dengan penjelasan singkat, misalnya No file provided pada presigned upload atau Invalid pagination parameters pada versi node-app. Upload asset yang gagal meneruskan status dari layanan upload (400, 401, 404, atau 500) dan dapat menempatkan teks responsnya di message. Teks tersebut terkadang berupa string JSON. Parameter query yang tidak valid pada GET /jobs menghasilkan 422, bukan 400.
401
Generate, jobs, assets, styles, dan node apps:
{ "message": "Presigned upload URL expired" } atau { "message": "Invalid presigned upload URL" }.
402 Pembayaran diperlukan
Untuk klien yang ditagih melalui API (API key, atau MCP yang menggunakan API key) yang saldo API-nya tidak mencukupi untuk job tersebut:
message 402 lainnya pada API publik:
Panggilan generate dengan Zero Data Retention pada workspace yang belum mengaktifkannya mengembalikan body ini, selalu berupa JSON:
402 sendiri. Body tersebut terkait saldo compute unit workspace, bukan saldo API.
403
404
Setiap 404 berupa { "message" }, misalnya untuk id job yang tidak dikenal:
Accept yang tidak ada membuat respons ini berupa HTML, kecuali Endpoint not found untuk model yang tidak dapat digunakan oleh key atau plan Anda, yang selalu berupa JSON. GET /jobs/{id} yang terautentikasi untuk id yang tidak dikenal tanpa Accept menghasilkan 404 text/html.
Operasi Agent yang tidak dikenal juga menghasilkan
404 { "message": "Endpoint not found" }, bukan bentuk Agent { "error", "code" }.
405
Body berupa teks biasa tanpa header Content-Type, bukan JSON, termasuk saat Accept bernilai application/json. Teksnya adalah metode ditambah method not allowed, misalnya GET method not allowed. Header Allow mencantumkan metode yang diterima oleh path tersebut.
413 Payload terlalu besar
Body permintaan yang terlalu besar ditolak dengan 413. Dari API itu sendiri, body mengikuti Accept:
413. Jangan mengirim file secara inline. Upload file dengan POST /assets dan teruskan URL yang dikembalikan dalam permintaan generate.
Unduhan input
Host yang mengembalikan404 atau 410 menghasilkan 422 permanen. Body berupa JSON, dan Accept berpengaruh:
410 menggunakan kalimat yang sama dengan 410. Penolakan permanen lainnya menggunakan Input file rejected: ….
Kegagalan unduhan yang dapat di-retry berupa 502 atau 504. Buat percabangan berdasarkan kode status, bukan body, lalu lakukan retry.
502 yang terus berulang untuk URL yang sama kemungkinan berarti URL tersebut diblokir atau rusak. Ganti URL-nya.
Kegagalan konversi ekspor 3D juga berupa 502. Jalur tersebut belum diuji secara langsung, sehingga body mungkin juga datang sebagai teks biasa Cloudflare error code: 502. Buat percabangan berdasarkan kode status dan lakukan retry. 502 yang terus berulang untuk URL model yang sama kemungkinan berarti URL tersebut diblokir atau rusak.
429 konkurensi
Saat job tidak dapat di-backlog, permintaan yang melebihi batas konkurensi dapat ditolak dengan 429 dan Content-Type: application/json:
limit adalah batas konkurensi Anda untuk jenis job ini. Batas ini dihitung per pengguna, bukan per workspace. Nilainya bersifat perkiraan: lonjakan singkat dapat diterima melebihinya, jadi jangan mengandalkan permintaan ke-limit + 1 sebagai yang gagal. jobType adalah kategori job internal, bukan path model publik. Jangan membuat percabangan berdasarkan field ini.
Krea 2 juga dapat hanya mengembalikan { "message": "CONCURRENCY_LIMIT_REACHED" }, tanpa limit atau jobType, saat antrean bersamanya penuh. Itu bukan batas Anda. Tunggu sejenak lalu lakukan retry.
Backlog hanya aktif jika plan menyertakannya (Pro ke atas), model mendukungnya, dan permintaan bukan Zero Data Retention. Permintaan Krea 2 saat ini tidak di-backlog pada plan apa pun, sehingga mengembalikan 429 saat melebihi batas. Saat backlog aktif, job tambahan diterima dengan status: "backlogged" dan dimulai begitu slot tersedia. Tidak ada batas backlog terpisah. Lihat Rate Limits.
API tidak mengirim Retry-After atau X-RateLimit-*. Respons memang menyertakan cf-ray. Saat menerima 429, lakukan retry dengan exponential backoff setelah job yang sedang berjalan selesai (lakukan polling GET /jobs/{id}, atau gunakan webhook).
Jika penyelesaian job berikutnya menghabiskan saldo, job yang masih berada di backlog akan gagal dengan error.code "insufficient_balance". Itu adalah job yang gagal, bukan HTTP 402. Job tersebut tidak mengirim webhook, jadi lakukan polling GET /jobs/{id} untuk job yang di-backlog.
Agent operation API
POST /agent/{operation} dan GET /agent/session/{sessionId} mengembalikan { "error", "code"?, "allowedModels"? }. Hanya error yang wajib. allowedModels menggunakan camelCase. Giliran yang gagal setelah diterima muncul sebagai status: "failed" pada sesi, bukan sebagai salah satu error HTTP ini. Lihat Agent.
Kode error Agent yang tidak dikenali tetap berupa
422 dengan { "error", "code" }. 404 operasi tidak dikenal dan 500 yang tidak tertangani menggunakan { "message" } dan mengikuti Accept.
error.code job yang gagal
GET /jobs dan GET /jobs/{id} hanya mengisi error saat status bernilai "failed". Tidak ada result yang dapat digunakan:
Pengiriman webhook untuk job yang gagal menggunakan objek job yang sama, termasuk
error. Pengiriman untuk job yang dibatalkan tidak memiliki error. Payload yang lebih besar dari 256 KiB tidak dikirim, dan tidak ada pengiriman lebih lanjut untuk job tersebut, jadi lakukan polling GET /jobs/{id} sebagai gantinya. Verifikasi signature sebelum Anda memercayai body. Lihat Webhooks.
Debugging
Tidak ada header request-id Krea. Setiap respons menyertakan headercf-ray milik Cloudflare. Tidak ada header Retry-After atau X-RateLimit-* yang dikirim.
Saat Anda menulis ke support@krea.ai, sertakan:
job_id, jika panggilan membuat atau merujuk ke sebuah job- Waktu dan endpoint
- Untuk error saat permintaan, nilai
cf-ray
Access-Control-Allow-Origin bernilai *. Pada generate, jobs, assets, styles, dan node apps, Access-Control-Expose-Headers tidak diatur, sehingga fetch di browser tidak dapat membaca cf-ray, Deprecation, atau Sunset. Salin cf-ray dari log jaringan, atau dari klien sisi server.
Pada setiap respons, periksa Deprecation dan Sunset sebelum model berhenti menerima panggilan. Lihat Deprecations.
Langkah berikutnya
Job Lifecycle
Lakukan polling status hingga job selesai, gagal, atau dibatalkan
Webhooks
Verifikasi signature pada pengiriman job yang gagal
Rate Limits
Kapan job tambahan di-backlog dan kapan mengembalikan 429
API Keys & Billing
Isi ulang saldo API setelah menerima 402