错误与调试

调用可能在两个环节失败：请求可能立即被拒绝并返回 HTTP 错误，也可能被接受后最终以 status: "failed" 结束。失败和取消的任务不会计费，你只需为已完成的任务付费。在节点应用（node app）中，应用自身的任务从不计费；每个生成节点或 LLM 节点在其自身任务完成时计费。某个节点失败不会取消并行节点或其他分支，因此在应用已经失败之后才完成的节点同样会计费，且这些费用不予退还。失败、被取消或从未启动的节点不计费。请参阅 API Keys & Billing。

请求时错误与失败任务

请求时错误会返回 4xx 或 5xx 状态码，不会创建任务。请按下文说明读取响应体。 失败任务在提交时返回成功状态码。请轮询 GET /jobs/{id} 或等待 webhook。任务结束时，status 为 "failed"，失败信息位于顶层 error 对象中。不要读取失败任务的 result：它会被省略（或为 null），只有当 status 为 "completed" 时才包含输出。cancelled 任务既没有 result，也没有 error。请根据 error.code 进行分支处理。message 可能被省略，而且对于 provider_error 和 internal，它是提供方返回的自由格式文本。不要解析 message。

if (job.status === "failed") {
  switch (job.error?.code ?? "internal") {
    case "content_policy":
    case "model_unavailable":
      // 重试相同的请求很可能会再次失败。请修改输入或更换模型。
      break;
    case "insufficient_balance":
      // 充值 API 余额后再重新提交。
      break;
    default:
      // timeout、auto_cancelled、provider_error、internal、node_app_node_failed，
      // 或未知的 code：以退避方式重新提交。
  }
}

响应体

在 generate、jobs、assets、styles 和 node apps 接口上，当响应体为 JSON 时，请读取 message ?? error，这两个字段之一会携带摘要信息。部分 5xx 响应体不是 JSON，例如响应体为纯文本 error code: 502 的 502。请进行防御性解析：如果响应体不是 JSON，就根据 HTTP 状态码进行分支处理。大多数失败使用 { "message": "..." }，有时带有额外字段（limit、jobType、modelAccessDenial）。无效 JSON 以及下文提到的少数处理程序则使用 { "error": "..." }。 /mcp 等 MCP 端点返回 JSON-RPC 错误 { "jsonrpc", "id", "error": { "code", "message" } }，而不是本页介绍的 HTTP 响应体。

发送 `Accept: application/json`

如果不发送 Accept: application/json，部分错误会以 HTML 页面返回，导致 JSON 解析器失败。

当 Accept 为 application/json 或 */* 时，{ "message" } 错误（包括 401 和 404）以 JSON 返回。当缺少 Accept 或其值为 text/html 时，这些状态码会返回 HTML 页面（Content-Type: text/html），JSON 解析器会因此失败。这对不发送 Accept 请求头的客户端很重要，Python 的 urllib 就是其中之一。curl 默认发送 Accept: */*，Node 的 fetch 也是如此，因此除非你覆盖 Accept，两者都会收到 JSON。未经认证的 POST /generate/...、GET /jobs/{id}、GET /styles 和 GET /assets，在 Accept 为 */* 和 application/json 时返回 401 {"message":"Unauthorized"}，在缺少 Accept 或为 text/html 时返回 HTML 页面。已认证的 GET /jobs/{id} 请求未知 id 时，状态码也遵循同样规则：当 Accept 要求 JSON 时返回 404 JSON {"message":"Job not found or unauthorized"}，缺少 Accept 时返回 404 text/html。无效 JSON（400）和校验失败（422）使用 { "error" }，即使缺少 Accept 也会保持 JSON。已移除字段的 422、模型下线的 410、Zero Data Retention 的 402、节点应用的 { "error" } 响应，以及映射后的 Agent 操作 API 错误也是如此。准入 POST /generate/... 任务时返回的 402 和 429 同样是 JSON，即使使用浏览器的 Accept 也一样。 413 和 500 使用 { "message" }，与 401 和 404 一样遵循 Accept。

校验失败（`422`）

{
  "error": "Validation failed",
  "details": [
    {
      "field": "width",
      "message": "Too small: expected number to be >0",
      "code": "too_small"
    },
    {
      "field": "",
      "message": "Unrecognized key: \"foo\"",
      "code": "unrecognized_keys"
    },
    {
      "field": "prompt",
      "message": "Enter a prompt.",
      "code": "custom"
    }
  ]
}

details 会列出所有问题。field 是以 . 连接的路径（"image_style_references.0.url"）。对象级错误使用空字符串，如上例中的未知键。多个未知键会产生 Unrecognized keys: ...，field 同样为空。只有当 code 为 "invalid_type" 时才会附加 expected。无效的 X-Webhook-URL 请求头也使用同样的 422。带有无效查询参数的 GET /jobs 也返回这种 422，而不是 400。在工具内部执行的 Zero Data Retention 输入检查失败时，会返回 422，说明位于 message 中（使用 { "message" } 结构，因此 Accept 会产生影响）。请参阅 Zero Data Retention。

已移除和已弃用的字段（`422`）

已移除的 batchSize / batch_size 字段使用另一种 422，没有 details 数组：

{
  "error": "invalid_request",
  "reason": "removed_field",
  "field": "batchSize",
  "message": "Generation batch size is no longer supported. Submit one request per output.",
  "value": 2
}

batch_size 也以同样方式被移除。field 为你所发送的字段名。已弃用的字段别名使用 reason "deprecated_field" 或 "conflicting_fields"，并在适用时附带 replacement、sunset_date 和 migration_url。请根据 error 和 reason 进行分支处理，需要展示给用户的语句是 message。

已下线模型（`410`）

超过下线日期的模型会返回 410，并带有 Deprecation: true 和 Sunset 响应头（RFC 1123 日期）：

{
  "error": "model_unavailable",
  "reason": "deprecated",
  "message": "The model '<path>' was deprecated on <sunsetDate>. <reason> Use '<replacement>' instead.",
  "sunset_date": "YYYY-MM-DD",
  "replacement": "<optional>",
  "migration_url": "<optional>"
}

error 是稳定值 "model_unavailable"。没有推荐替代模型时，会省略 replacement 和 migration_url。重试同一模型会持续返回 410。如果设置了 replacement，请切换到该模型，并参阅弃用说明。已弃用但仍可用的模型会在每个响应（包括错误响应）中发送 Deprecation 和 Sunset。使用已弃用的字段别名时也是如此，包括其自身的 422。如果存在迁移指南，还会发送 Link: <migration_url>; rel="deprecation" 响应头。

状态码

状态码	含义
`400`	generate 请求体不是有效 JSON、节点应用的输入 URL 无法使用，或 asset 或节点应用参数无效。节点应用 execute 上的无效 JSON 返回 `500`。
`401`	凭证缺失或无效。
`402`	请求在任务开始前被拒绝。请参阅 402。
`403`	调用方已通过认证，但无权使用该资源。
`404`	没有匹配的路由、模型路径未知或你无权使用，或者任务、asset、风格或节点应用不存在。
`405`	该路径不允许使用此 HTTP 方法。
`410`	模型已下线。请参阅已下线模型。
`413`	请求体过大。请参阅 413。
`422`	校验失败、发送了已移除或已弃用的字段，或某个输入被永久拒绝。
`429`	超过并发上限且任务无法进入积压。该上限是近似值。
`500`	未处理的服务器错误。`{ "message": "Internal Error" }`，不包含异常文本。遵循 `Accept`。
`502`、`504`	可重试。`502` 以 Cloudflare 纯文本 `error code: 502` 返回，而不是 JSON，因此请根据状态码进行分支处理。`504` 也可能是纯文本。请参阅输入下载。

`400`

generate 上的无效 JSON 始终以 JSON 返回，无需 Accept 请求头：

{
  "error": "Invalid JSON: Expected property name or '}' in JSON at position 1 (line 1 column 2)"
}

节点应用 execute 对无法使用的输入 URL 使用 { "error" }：Invalid URL for input "<key>"，或 Failed to download URL for <key>: …。下载错误信息也涵盖临时性失败，因此与 generate 不同（参见输入下载），节点应用的下载失败始终返回 400。如果 URL 有效，可重试一次。 POST /node-apps/{id}/execute 上的无效 JSON 不会返回上述 generate 的 400，而是变成 500 { "message": "Internal Error" }，不包含异常文本，并遵循 Accept。 assets 和节点应用上的其他 400 响应为 { "message": "..." }，附带简短说明，例如预签名上传时的 No file provided，或节点应用版本接口上的 Invalid pagination parameters。asset 上传失败时会透传上传服务的状态码（400、401、404 或 500），并可能把其响应文本放入 message，该文本有时是一个 JSON 字符串。GET /jobs 上的无效查询参数返回 422，而不是 400。

`401`

generate、jobs、assets、styles 和 node apps：

{ "message": "Unauthorized" }

预签名上传返回 { "message": "Presigned upload URL expired" } 或 { "message": "Invalid presigned upload URL" }。

`402` 需要付款

对于按 API 计费的客户端（API 密钥，或使用 API 密钥的 MCP），如果 API 余额不足以支付该任务：

{
  "message": "Your API balance is separate from your workspace compute balance. Please top up your API balance to continue using the API."
}

请前往 krea.ai/app/api/ ↗ 充值。进行中的任务会继续完成。请参阅 API Keys & Billing。公开 API 上其他 402 的 message 值：

`message`	触发情况
`This tool is not available on your current plan.`	你的套餐或工作区不允许该模型有任何并发任务。
`MEMBER_USAGE_LIMIT_REACHED`	套餐启用了成员用量限制，且会超出该成员的预算。
`WORKSPACE_USAGE_LIMIT_REACHED`	套餐启用了成员用量限制，且会超出工作区的预算。
`MEMBER_LIMIT_VIOLATION`	工作区成员数超过了其套餐允许的数量。
`K3_ULTRA_ACCESS_REQUIRED`	在不含 Krea 3 Ultra 的套餐上，使用 `thinking_mode` 为 `"ultra"`（或旧版 `"max"`）且带有图像参考的 Krea 3。没有图像参考时，Ultra 会以 `"fast"` 运行。
`ENHANCER_RESOLUTION_LIMIT_REACHED`	放大（upscale）尺寸超出了免费套餐允许的范围。

在未启用 Zero Data Retention 的工作区上发起带 Zero Data Retention 的 generate 调用时，会返回以下响应体，且始终为 JSON：

{ "error": "Zero data retention is not enabled for this workspace." }

Agent 操作 API 使用其自身的 402 响应体，它们消耗的是工作区计算余额，而不是 API 余额。

`403`

`message` 或 `error`	触发情况
`Use an API key or a plugin session`	调用 Realtime 时未使用 API 密钥，也没有 OAuth 或插件会话。`{ "message" }`。
`This endpoint needs a workspace service API key`	Usage API，凭证不是工作区服务 API 密钥。`{ "message" }`。
`Your plan is not entitled to the usage API`	Usage API，套餐无权使用。`{ "message" }`。
`FEATURE_RESTRICTED`	模型策略拒绝。响应体还包含 `modelAccessDenial`。`{ "message" }`。
`MODEL_ACCESS_REQUIRED`	该模型仅限内部使用。`{ "message" }`。
`This node app cannot be used via the API.`	节点应用 execute。`{ "error" }`，始终为 JSON。
`Free users cannot run node apps`	在免费套餐工作区上执行节点应用。`{ "message" }`。
`You do not own this style`	修改或共享不属于你的风格。`{ "message" }`。

`404`

所有 404 都是 { "message" }，例如未知的任务 id：

{ "message": "Job not found or unauthorized" }

缺少 Accept 请求头时，这些响应会变成 HTML，唯一的例外是你的密钥或套餐无法使用的模型所返回的 Endpoint not found，它始终为 JSON。已认证的 GET /jobs/{id} 请求未知 id 且未带 Accept 时，返回 404 text/html。

`message`	触发情况
`Not Found`	没有路由匹配该路径。
`Endpoint not found`	`/generate` 下的模型路径未知，或此 API 密钥或套餐无法使用。
`Job not found or unauthorized`	任务 id 缺失或无效，包括 `DELETE /jobs/{id}`。
`Asset not found`	asset 不存在。
`Style not found`	风格不存在。修改或共享不属于你的风格时返回 `Style not found or you are not the owner`。
`Node app not found`	节点应用不存在。
`Workspace not found`	Usage API，工作区不存在。

未知的 Agent 操作同样返回 404 { "message": "Endpoint not found" }，而不是 Agent 的 { "error", "code" } 结构。

`405`

响应体为纯文本，没有 Content-Type 响应头，不是 JSON，即使 Accept 为 application/json 也是如此。文本内容为请求方法加上 method not allowed，例如 GET method not allowed。Allow 响应头会列出该路径接受的方法。

`413` 请求体过大

过大的请求体会被拒绝并返回 413。由 API 本身返回时，响应体遵循 Accept：

{ "message": "Payload Too Large" }

非常大的请求体可能在到达 API 之前就被拒绝，并返回 HTML 格式的 413 页面。不要以内联方式发送文件。请通过 POST /assets 上传文件，并在 generate 请求中传入返回的 URL。

输入下载

文件主机返回 404 或 410 时，属于永久性的 422。响应体为 JSON，且 Accept 会产生影响：

{ "message": "Input file rejected: fetching <url> returned HTTP 404" }

主机返回 410 时使用同样的语句，只是状态码为 410。其他永久性拒绝使用 Input file rejected: …。可重试的下载失败返回 502 或 504。请根据状态码而不是响应体进行分支处理，并重试。

状态码	你收到的内容	是否重试？
`422`	主机返回 `404` 时为 JSON `{ "message": "Input file rejected: fetching <url> returned HTTP 404" }`。主机返回 `410` 时使用同样的语句，状态码为 `410`。	否。该失败是永久性的。
`502`	Cloudflare 纯文本 `error code: 502`，`Content-Type: text/plain; charset=UTF-8`。已确认在文件主机返回 `503`、`500` 或 `429`，以及域名无法解析时出现。	是。根据状态码进行分支处理。
`504`	未经实际测试，也可能以 Cloudflare 纯文本返回。	是。根据状态码进行分支处理。

如果同一 URL 反复返回 502，很可能意味着该 URL 被屏蔽或已失效。请更换 URL。 3D 导出转换失败同样返回 502。该路径未经实际测试，因此响应体也可能以 Cloudflare 纯文本 error code: 502 返回。请根据状态码进行分支处理并重试。如果同一模型 URL 反复返回 502，很可能意味着该 URL 被屏蔽或已失效。

`429` 并发

当任务无法进入积压时，超过并发上限的请求可能会被拒绝，返回 429 和 Content-Type: application/json：

{
  "message": "CONCURRENCY_LIMIT_REACHED",
  "limit": 4,
  "jobType": "k2"
}

limit 是你在这类任务上的并发上限，按用户而不是按工作区计算。它是近似值：短时间内的突发请求可能在超出上限后仍被接受，因此不要指望第 limit + 1 个请求一定会失败。jobType 是内部任务类别，而不是公开的模型路径，不要据此进行分支处理。当 Krea 2 的共享队列已满时，它也可能只返回 { "message": "CONCURRENCY_LIMIT_REACHED" }，不带 limit 或 jobType。这并不是你的上限，请退避后重试。只有当套餐包含积压功能（Pro 及以上）、模型支持积压，且请求不是 Zero Data Retention 请求时，积压才会启用。目前任何套餐下的 Krea 2 请求都不会进入积压，因此超过上限时会返回 429。积压启用时，额外的任务会以 status: "backlogged" 被接受，并在有空闲槽位时开始处理。积压没有单独的容量上限。请参阅速率限制。 API 不会发送 Retry-After 或 X-RateLimit-*，但响应中包含 cf-ray。收到 429 时，请等待进行中的任务完成后（轮询 GET /jobs/{id} 或使用 webhook）再以指数退避方式重试。如果之后某个任务完成时耗尽了余额，仍在积压中的任务会以 error.code "insufficient_balance" 失败。这属于失败任务，而不是 HTTP 402。这些任务不会发送 webhook，因此请对积压中的任务轮询 GET /jobs/{id}。

Agent 操作 API

POST /agent/{operation} 和 GET /agent/session/{sessionId} 返回 { "error", "code"?, "allowedModels"? }。只有 error 是必需的。allowedModels 使用 camelCase。轮次在被接受之后才失败时，会在会话上显示为 status: "failed"，而不是以下这些 HTTP 错误之一。请参阅 Agent API。

状态码	响应体
`400`	`{ "error": "Invalid JSON body" }`
`401`	`{ "error": "Unauthorized" }`
`402`	`{ "error": "Insufficient compute balance for an Agent turn", "code": "compute_limit" }`，或 `{ "error": "Free plan Agent message limit reached. Upgrade to keep using the Agent", "code": "free_message_limit" }`。
`403`	`{ "error": "Model is not included in the workspace plan", "code": "model_not_entitled", "allowedModels": ["..."] }`。
`404`	未知操作：`{ "message": "Endpoint not found" }`。其他情况为 `{ "error": "Session not found or not accessible", "code": "not_found" }`，或 `{ "error": "<file reference error>", "code": "attachment_not_found" }`。
`409`	`{ "error": "...", "code": "conflict" }`。
`422`	输入有误：`{ "error": "Validation failed", "details": [...] }`，与校验失败相同。其他映射后的错误为 `{ "error": "<message>" }`，存在 code 时附带 `code`。桌面应用未连接时没有 `code`，消息以 `That desktop app is not connected` 开头。

无法识别的 Agent 错误码仍返回 422，响应体为 { "error", "code" }。未知操作的 404 和未处理的 500 使用 { "message" } 并遵循 Accept。

失败任务的 `error.code`

GET /jobs 和 GET /jobs/{id} 仅在 status 为 "failed" 时设置 error，此时没有可用的 result：

{
  "status": "failed",
  "error": {
    "code": "content_policy",
    "message": "An external provider's moderation systems rejected the generation."
  }
}

请根据 error.code 进行分支处理，切勿解析 message。message 可能被省略。provider_error 和 internal 的 message 是自由格式文本，internal 的 message 可能是提供方的原始文本，例如 failed to download media from the provided URL。任何无法识别的 code 都应视为 internal。

`code`	`message`	处理方式
`content_policy`	`Krea's moderation systems rejected the generation.` 或 `An external provider's moderation systems rejected the generation.`	修改提示词或输入。相同的请求很可能会再次被拒绝。
`timeout`	`An external provider did not complete the generation in sufficient time.`	重试该任务。
`insufficient_balance`	省略。节点应用可能改为返回 `You are out of compute units. Add more compute units to continue running this node app.`	充值后重新提交。该任务此前已被接受，HTTP 调用并未返回 `402`。
`auto_cancelled`	`Job repeatedly failed healthchecks and was automatically cancelled.`	重新提交该任务。
`model_unavailable`	通常为提供方自己的文本。没有时为 `The provider retired this model. It no longer accepts new generations.`	停止调用该模型。如有替代模型，请使用弃用说明中列出的替代模型。
`provider_error`	通常为提供方自己的文本。	以退避方式重试。
`internal`	自由格式，或省略。	稍后重试。联系支持时请提供 `job_id`。
`node_app_node_failed`	`Node "<type>" failed: <detail>` 或 `Node "<type>" failed.`	阅读 `message`。如果节点遇到的是超时等临时问题，请重新运行应用；否则请先修复该节点。应用自身的任务从不计费；每个生成节点或 LLM 节点在其自身任务完成时计费。某个节点失败不会取消并行节点或其他分支，因此在应用已经失败之后才完成的节点同样会计费，且这些费用不予退还。失败、被取消或从未启动的节点不计费。公开的任务对象中不包含节点 id 和节点类型。

失败任务的 webhook 推送使用相同的任务对象，包括 error。取消任务的推送不含 error。超过 256 KiB 的负载不会发送，并且该任务不会再有后续推送，因此请改为轮询 GET /jobs/{id}。在信任响应体之前，请先验证签名。请参阅 Webhooks。

调试

Krea 没有请求 id 响应头，但每个响应都包含 Cloudflare 的 cf-ray 响应头。不会发送 Retry-After 或 X-RateLimit-* 响应头。发送邮件至 support@krea.ai 时，请提供：

job_id（如果该调用创建或涉及某个任务）
时间和端点
对于请求时错误，提供 cf-ray 的值

Access-Control-Allow-Origin 为 *。在 generate、jobs、assets、styles 和 node apps 接口上未设置 Access-Control-Expose-Headers，因此浏览器中的 fetch 无法读取 cf-ray、Deprecation 或 Sunset。请从网络日志或服务端客户端中复制 cf-ray。在任何响应中，都应在模型停止接受调用之前检查 Deprecation 和 Sunset。请参阅弃用说明。

下一步

任务生命周期

轮询状态，直到任务完成、失败或被取消

Webhooks

验证失败任务推送的签名

速率限制

额外任务何时进入积压、何时返回 429

API Keys & Billing

收到 402 后充值 API 余额

快速开始

Krea 3

Krea 2

核心概念

代码示例

教程

请求时错误与失败任务

响应体

发送 `Accept: application/json`

校验失败（`422`）

已移除和已弃用的字段（`422`）

已下线模型（`410`）

状态码

`400`

`401`

`402` 需要付款

`403`

`404`

`405`

`413` 请求体过大

输入下载

`429` 并发

Agent 操作 API

失败任务的 `error.code`

调试

下一步

任务生命周期

Webhooks

速率限制

API Keys & Billing

​请求时错误与失败任务

​响应体

​发送 Accept: application/json

​校验失败（422）

​已移除和已弃用的字段（422）

​已下线模型（410）

​状态码

​400

​401

​402 需要付款

​403

​404

​405

​413 请求体过大

​输入下载

​429 并发

​Agent 操作 API

​失败任务的 error.code

​调试

​下一步

任务生命周期

Webhooks

速率限制

API Keys & Billing

请求时错误与失败任务

响应体

发送 `Accept: application/json`

校验失败（`422`）

已移除和已弃用的字段（`422`）

已下线模型（`410`）

状态码

`400`

`401`

`402` 需要付款

`403`

`404`

`405`

`413` 请求体过大

输入下载

`429` 并发

Agent 操作 API

失败任务的 `error.code`

调试

下一步