Errores y depuración

Una llamada puede fallar en dos momentos. La solicitud puede rechazarse de inmediato con un error HTTP, o puede aceptarse y terminar más tarde con status: "failed". Los jobs fallidos y cancelados no se facturan. Solo pagas por los jobs completados. En una node app, el job propio de la app nunca se factura. Cada nodo de generación o de LLM se cobra cuando se completa su propio job. Un fallo no cancela los nodos paralelos ni otras ramas, por lo que un nodo que se completa después de que la app ya haya fallado también se cobra, y esos cargos no se reembolsan. Un nodo que falla, se cancela o nunca empieza no se cobra. Consulta Claves de API y facturación.

Errores en la solicitud y jobs fallidos

Los errores en la solicitud devuelven un estado 4xx o 5xx. No se crea ningún job. Lee el cuerpo como se describe a continuación. Los jobs fallidos devuelven un estado de éxito al enviarse. Consulta GET /jobs/{id} o espera un webhook. Cuando el job termina, status es "failed" y el fallo es el objeto error de nivel superior. No leas result en un job fallido: se omite (o es null). Solo contiene la salida cuando status es "completed". Un job cancelled no tiene ni result ni error. Ramifica según error.code. message puede omitirse y, para provider_error e internal, es texto libre del proveedor. No analices message.

if (job.status === "failed") {
  switch (job.error?.code ?? "internal") {
    case "content_policy":
    case "model_unavailable":
      // Reintentar la misma solicitud probablemente vuelva a fallar. Cambia la entrada o el modelo.
      break;
    case "insufficient_balance":
      // Recarga el saldo de API y vuelve a enviar.
      break;
    default:
      // timeout, auto_cancelled, provider_error, internal, node_app_node_failed,
      // o un código desconocido: vuelve a enviar con retroceso.
  }
}

Cuerpos de respuesta

En generate, jobs, assets, styles y node apps, lee message ?? error cuando el cuerpo sea JSON. Uno de esos dos campos contiene el resumen. Algunos cuerpos 5xx no son JSON, incluido un 502 cuyo cuerpo es el texto plano error code: 502. Analiza de forma defensiva: si el cuerpo no es JSON, ramifica según el estado HTTP. La mayoría de los fallos usan { "message": "..." }, a veces con campos adicionales (limit, jobType, modelAccessDenial). El JSON inválido y algunos handlers que se indican más abajo usan { "error": "..." } en su lugar. Los endpoints MCP como /mcp devuelven errores JSON-RPC, { "jsonrpc", "id", "error": { "code", "message" } }, no los cuerpos HTTP de esta página.

Envía `Accept: application/json`

Sin Accept: application/json, algunos errores llegan como una página HTML y un parser de JSON fallará.

Los errores { "message" }, incluidos 401 y 404, son JSON cuando Accept es application/json o */*. Cuando falta Accept, o es text/html, esos estados son una página HTML (Content-Type: text/html) y un parser de JSON fallará. Esto es importante para los clientes que no envían el encabezado Accept. urllib de Python es uno de ellos. curl envía Accept: */* de forma predeterminada, y fetch de Node también, por lo que ambos reciben JSON a menos que sobrescribas Accept. Las solicitudes sin autenticar a POST /generate/..., GET /jobs/{id}, GET /styles y GET /assets devuelven 401 {"message":"Unauthorized"} para */* y application/json, y una página HTML cuando falta Accept o es text/html. Una solicitud autenticada a GET /jobs/{id} con un id desconocido hace lo mismo con el estado: 404 JSON {"message":"Job not found or unauthorized"} cuando Accept pide JSON, y 404 text/html cuando falta Accept. El JSON inválido (400) y la validación (422) usan { "error" } y siguen siendo JSON incluso cuando falta Accept. Lo mismo ocurre con el 422 de campo eliminado, el 410 de retiro, el 402 de Zero Data Retention, las respuestas { "error" } de node apps y los errores mapeados de la API de operaciones de Agent. Los 402 y 429 al admitir un job de POST /generate/... también son JSON, incluso con un Accept de navegador. 413 y 500 usan { "message" } y siguen a Accept, como 401 y 404.

Validación (`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 enumera todos los problemas. field es la ruta unida con . ("image_style_references.0.url"). Los errores a nivel de objeto usan una cadena vacía, como con la clave desconocida de arriba. Varias claves desconocidas producen Unrecognized keys: ... y el mismo field vacío. expected solo se añade cuando code es "invalid_type". Un encabezado X-Webhook-URL inválido usa este mismo 422. GET /jobs con parámetros de consulta inválidos también devuelve este 422. No es un 400. Una comprobación de entrada de Zero Data Retention que falla dentro de la herramienta devuelve 422 con la explicación en message (el formato { "message" }, así que Accept importa). Consulta Zero Data Retention.

Campos eliminados y obsoletos (`422`)

El campo eliminado batchSize / batch_size usa un 422 distinto. No hay arreglo 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 se elimina de la misma manera. field es el nombre que hayas enviado. Un alias de campo obsoleto usa reason "deprecated_field" o "conflicting_fields", además de replacement, sunset_date y migration_url cuando corresponda. Ramifica según error y reason. La frase para mostrar a una persona es message.

Modelos retirados (`410`)

Un modelo que ha superado su fecha de retiro devuelve 410 con Deprecation: true y un encabezado Sunset (una fecha 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 es el valor estable "model_unavailable". replacement y migration_url se omiten cuando no hay un reemplazo recomendado. Reintentar con el mismo modelo seguirá devolviendo 410. Cambia a replacement cuando esté definido y consulta Deprecaciones. Un modelo obsoleto pero todavía activo envía Deprecation y Sunset en cada respuesta, incluidos los errores. Usar un alias de campo obsoleto hace lo mismo, incluso en su propio 422. Cuando existe una guía de migración, también se envía un encabezado Link: <migration_url>; rel="deprecation".

Códigos de estado

Estado	Significado
`400`	Un cuerpo de generate no es JSON válido, no se pudo usar una URL de entrada de una node app, o los parámetros de un asset o de una node app son inválidos. El JSON inválido en la ejecución de una node app es `500`.
`401`	Las credenciales faltan o son inválidas.
`402`	La solicitud se rechazó antes de que empezara un job. Consulta 402.
`403`	El llamante está autenticado, pero no tiene permiso para usar este recurso.
`404`	Ninguna ruta coincidió, la ruta del modelo es desconocida o no está disponible para ti, o falta un job, asset, style o node app.
`405`	El método HTTP no está permitido para esta ruta.
`410`	El modelo está retirado. Consulta Modelos retirados.
`413`	El cuerpo de la solicitud es demasiado grande. Consulta 413.
`422`	Falló la validación, se envió un campo eliminado u obsoleto, o una entrada se rechazó de forma permanente.
`429`	Se superó el límite de concurrencia y el job no puede pasar al backlog. El límite es aproximado.
`500`	Error de servidor no controlado. `{ "message": "Internal Error" }`. Sin texto de la excepción. Sigue a `Accept`.
`502`, `504`	Se pueden reintentar. Un `502` llega como texto plano de Cloudflare `error code: 502`, no como JSON, así que ramifica según el código de estado. `504` también puede ser texto plano. Consulta Descargas de entradas.

`400`

El JSON inválido en generate siempre es JSON, sin necesidad del encabezado Accept:

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

La ejecución de node apps usa { "error" } para una URL de entrada que no puede usar: Invalid URL for input "<key>" o Failed to download URL for <key>: …. El mensaje de descarga también cubre fallos temporales, así que, a diferencia de generate (consulta Descargas de entradas), un fallo de descarga en una node app siempre es 400. Reinténtalo una vez si la URL es válida. El JSON inválido en POST /node-apps/{id}/execute no es el 400 de generate descrito arriba. Se convierte en un 500 { "message": "Internal Error" }, sin texto de la excepción, y sigue a Accept. Otras respuestas 400 en assets y node apps son { "message": "..." } con una explicación breve, por ejemplo No file provided en una subida prefirmada o Invalid pagination parameters en las versiones de una node app. Una subida de asset fallida transmite el estado del servicio de subida (400, 401, 404 o 500) y puede incluir el texto de su respuesta en message. Ese texto a veces es una cadena JSON. Los parámetros de consulta inválidos en GET /jobs son 422, no 400.

`401`

Generate, jobs, assets, styles y node apps:

{ "message": "Unauthorized" }

Las subidas prefirmadas devuelven { "message": "Presigned upload URL expired" } o { "message": "Invalid presigned upload URL" }.

`402` Pago requerido

Para un cliente facturado por API (una clave de API, o MCP con una clave de API) cuyo saldo de API no cubre el job:

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

Recarga en krea.ai/app/api/ ↗. Los jobs en curso terminan. Consulta Claves de API y facturación. Otros valores de message para 402 en la API pública:

`message`	Cuándo
`This tool is not available on your current plan.`	Tu plan o workspace no permite jobs simultáneos para este modelo.
`MEMBER_USAGE_LIMIT_REACHED`	El plan aplica límites de uso por miembro y se superaría el presupuesto de este miembro.
`WORKSPACE_USAGE_LIMIT_REACHED`	El plan aplica límites de uso por miembro y se superaría el presupuesto del workspace.
`MEMBER_LIMIT_VIOLATION`	El workspace tiene más miembros de los que permite su plan.
`K3_ULTRA_ACCESS_REQUIRED`	Krea 3 con `thinking_mode` `"ultra"` (o el antiguo `"max"`) e imágenes de referencia, en un plan sin Krea 3 Ultra. Sin imágenes de referencia, Ultra se ejecuta como `"fast"`.
`ENHANCER_RESOLUTION_LIMIT_REACHED`	Un escalado es mayor de lo que permite el plan gratuito.

Una llamada a generate con Zero Data Retention en un workspace que no lo tiene habilitado devuelve este cuerpo, siempre en JSON:

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

La API de operaciones de Agent usa sus propios cuerpos 402. Estos se descuentan del saldo de cómputo del workspace, no del saldo de API.

`403`

`message` o `error`	Cuándo
`Use an API key or a plugin session`	Realtime, llamado sin una clave de API ni una sesión OAuth o de plugin. `{ "message" }`.
`This endpoint needs a workspace service API key`	Usage API, la credencial no es una clave de API de servicio del workspace. `{ "message" }`.
`Your plan is not entitled to the usage API`	Usage API, el plan no tiene acceso. `{ "message" }`.
`FEATURE_RESTRICTED`	Denegación por la política del modelo. El cuerpo también incluye `modelAccessDenial`. `{ "message" }`.
`MODEL_ACCESS_REQUIRED`	El modelo es solo para uso interno. `{ "message" }`.
`This node app cannot be used via the API.`	Ejecución de node app. `{ "error" }`, siempre JSON.
`Free users cannot run node apps`	Ejecución de node app en un workspace con plan gratuito. `{ "message" }`.
`You do not own this style`	Modificar o compartir un style que no te pertenece. `{ "message" }`.

`404`

Todos los 404 son { "message" }, por ejemplo, para un id de job desconocido:

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

Si falta el encabezado Accept, estas respuestas son HTML, excepto Endpoint not found para un modelo que tu clave o plan no puede usar, que siempre es JSON. Una solicitud autenticada a GET /jobs/{id} con un id desconocido y sin Accept es 404 text/html.

`message`	Cuándo
`Not Found`	Ninguna ruta coincidió con la ruta solicitada.
`Endpoint not found`	Una ruta de modelo bajo `/generate` que es desconocida, o que esta clave de API o plan no puede usar.
`Job not found or unauthorized`	Id de job inexistente o inválido, incluido `DELETE /jobs/{id}`.
`Asset not found`	Asset inexistente.
`Style not found`	Style inexistente. Modificar o compartir uno que no te pertenece devuelve `Style not found or you are not the owner`.
`Node app not found`	Node app inexistente.
`Workspace not found`	Usage API, el workspace no existe.

Una operación de Agent desconocida también es 404 { "message": "Endpoint not found" }, no el formato { "error", "code" } de Agent.

`405`

El cuerpo es texto plano sin encabezado Content-Type, no JSON, incluso cuando Accept es application/json. El texto es el método seguido de method not allowed, por ejemplo GET method not allowed. Un encabezado Allow enumera los métodos que acepta la ruta.

`413` Carga demasiado grande

Un cuerpo de solicitud demasiado grande se rechaza con 413. Desde la propia API, el cuerpo sigue a Accept:

{ "message": "Payload Too Large" }

Un cuerpo muy grande puede rechazarse antes de llegar a la API, con una página HTML de 413. No envíes archivos en línea. Sube el archivo con POST /assets y pasa la URL devuelta en la solicitud de generate.

Descargas de entradas

Un host que devuelve 404 o 410 es un 422 permanente. El cuerpo es JSON y Accept importa:

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

Un 410 del host usa la misma frase con 410. Otros rechazos permanentes usan Input file rejected: …. Un fallo de descarga que se puede reintentar es 502 o 504. Ramifica según el código de estado, no según el cuerpo, y reintenta.

Estado	Lo que recibes	¿Reintentar?
`422`	JSON `{ "message": "Input file rejected: fetching <url> returned HTTP 404" }` cuando el host devuelve `404`. Un `410` del host usa la misma frase con `410`.	No. El fallo es permanente.
`502`	Texto plano de Cloudflare `error code: 502`, con `Content-Type: text/plain; charset=UTF-8`. Confirmado cuando el host del archivo devuelve `503`, `500` o `429`, y cuando el dominio no se resuelve.	Sí. Ramifica según el código de estado.
`504`	No probado en vivo. También puede llegar como texto plano de Cloudflare.	Sí. Ramifica según el código de estado.

Un 502 que se repite constantemente para la misma URL probablemente significa que la URL está bloqueada o rota. Cambia la URL. Los fallos de conversión en la exportación 3D también son 502. Esa ruta no se probó en vivo, por lo que el cuerpo también puede llegar como texto plano de Cloudflare error code: 502. Ramifica según el código de estado y reintenta. Un 502 que se repite constantemente para la misma URL de modelo probablemente significa que la URL está bloqueada o rota.

`429` de concurrencia

Cuando el job no puede pasar al backlog, una solicitud que supera el límite de concurrencia puede rechazarse con 429 y Content-Type: application/json:

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

limit es tu límite de concurrencia para este tipo de job. Se cuenta por usuario, no por workspace. Es aproximado: una ráfaga breve puede aceptarse por encima de él, así que no cuentes con que la solicitud limit + 1 sea la que falle. jobType es una categoría interna de job, no la ruta pública del modelo. No ramifiques según él. Krea 2 también puede devolver solo { "message": "CONCURRENCY_LIMIT_REACHED" }, sin limit ni jobType, cuando su cola compartida está llena. Ese no es tu límite. Espera y reintenta. El backlog solo está activo cuando el plan lo incluye (Pro y superiores), el modelo lo admite y la solicitud no es de Zero Data Retention. Actualmente, las solicitudes de Krea 2 no pasan al backlog en ningún plan, por lo que devuelven 429 al superar el límite. Cuando está activo, el job adicional se acepta con status: "backlogged" y comienza en cuanto queda un espacio libre. No hay un límite de backlog independiente. Consulta Límites de tasa. La API no envía Retry-After ni X-RateLimit-*. La respuesta sí incluye cf-ray. Ante un 429, reintenta con retroceso exponencial después de que terminen los jobs en curso (consulta GET /jobs/{id} o usa un webhook). Si una finalización posterior agota el saldo, los jobs que siguen en el backlog fallan con error.code "insufficient_balance". Es un job fallido, no un 402 HTTP. Esos jobs no envían webhook, así que consulta GET /jobs/{id} para los jobs en backlog.

API de operaciones de Agent

POST /agent/{operation} y GET /agent/session/{sessionId} devuelven { "error", "code"?, "allowedModels"? }. Solo error es obligatorio. allowedModels está en camelCase. Un turno que falla después de haber sido aceptado aparece como status: "failed" en la sesión, no como uno de estos errores HTTP. Consulta Agent.

Estado	Cuerpo
`400`	`{ "error": "Invalid JSON body" }`
`401`	`{ "error": "Unauthorized" }`
`402`	`{ "error": "Insufficient compute balance for an Agent turn", "code": "compute_limit" }` o `{ "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`	Operación desconocida: `{ "message": "Endpoint not found" }`. En otros casos, `{ "error": "Session not found or not accessible", "code": "not_found" }` o `{ "error": "<file reference error>", "code": "attachment_not_found" }`.
`409`	`{ "error": "...", "code": "conflict" }`.
`422`	Entrada incorrecta: `{ "error": "Validation failed", "details": [...] }` como en Validación. Otros errores mapeados son `{ "error": "<message>" }` más `code` cuando existe. Una app de escritorio desconectada no tiene `code`; el mensaje empieza por `That desktop app is not connected`.

Un código de error de Agent no reconocido sigue siendo 422 con { "error", "code" }. El 404 de operación desconocida y un 500 no controlado usan { "message" } y siguen a Accept.

`error.code` de jobs fallidos

GET /jobs y GET /jobs/{id} incluyen error solo cuando status es "failed". No hay un result utilizable:

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

Ramifica según error.code. Nunca analices message.message puede omitirse. Los mensajes de provider_error e internal son texto libre, y un mensaje internal puede ser texto sin procesar del proveedor, como failed to download media from the provided URL. Trata cualquier code que no reconozcas como internal.

`code`	`message`	Qué hacer
`content_policy`	`Krea's moderation systems rejected the generation.` o `An external provider's moderation systems rejected the generation.`	Cambia el prompt o las entradas. La misma solicitud probablemente vuelva a rechazarse.
`timeout`	`An external provider did not complete the generation in sufficient time.`	Reintenta el job.
`insufficient_balance`	Se omite. Una node app puede devolver en su lugar `You are out of compute units. Add more compute units to continue running this node app.`	Recarga y vuelve a enviar. Este job se aceptó antes; la llamada HTTP no devolvió `402`.
`auto_cancelled`	`Job repeatedly failed healthchecks and was automatically cancelled.`	Vuelve a enviar el job.
`model_unavailable`	Normalmente, el texto propio del proveedor. `The provider retired this model. It no longer accepts new generations.` cuando no hay ninguno.	Deja de llamar a este modelo. Usa el reemplazo indicado en Deprecaciones cuando exista.
`provider_error`	Normalmente, el texto propio del proveedor.	Reintenta con retroceso.
`internal`	Texto libre, o se omite.	Reintenta más tarde. Indica el `job_id` si contactas a soporte.
`node_app_node_failed`	`Node "<type>" failed: <detail>` o `Node "<type>" failed.`	Lee `message`. Si el nodo tuvo un problema temporal, como un timeout, vuelve a ejecutar la app. De lo contrario, corrige primero ese nodo. El job propio de la app nunca se factura. Cada nodo de generación o de LLM se cobra cuando se completa su propio job. Un fallo no cancela los nodos paralelos ni otras ramas, por lo que un nodo que se completa después de que la app ya haya fallado también se cobra, y esos cargos no se reembolsan. Un nodo que falla, se cancela o nunca empieza no se cobra. El id y el tipo del nodo no aparecen en el job público.

Las entregas de webhook de un job fallido usan el mismo objeto de job, incluido error. Una entrega de cancelación no tiene error. Un payload de más de 256 KiB no se envía, y no se realizan más entregas para ese job, así que consulta GET /jobs/{id} en su lugar. Verifica la firma antes de confiar en el cuerpo. Consulta Webhooks.

Depuración

No hay un encabezado de id de solicitud de Krea. Todas las respuestas sí incluyen el encabezado cf-ray de Cloudflare. No se envía ningún encabezado Retry-After ni X-RateLimit-*. Cuando escribas a support@krea.ai, incluye:

El job_id, cuando la llamada creó o hizo referencia a un job
La hora y el endpoint
Para un error en la solicitud, el valor de cf-ray

Access-Control-Allow-Origin es *. En generate, jobs, assets, styles y node apps, Access-Control-Expose-Headers no está definido, por lo que fetch en el navegador no puede leer cf-ray, Deprecation ni Sunset. Copia cf-ray desde el registro de red o desde un cliente del lado del servidor. En cualquier respuesta, revisa Deprecation y Sunset antes de que el modelo deje de aceptar llamadas. Consulta Deprecaciones.

Próximos pasos

Ciclo de vida de un job

Consulta el estado hasta que el job se complete, falle o se cancele

Webhooks

Verifica la firma en la entrega de un job fallido

Límites de tasa

Cuándo los jobs adicionales pasan al backlog y cuándo devuelven 429

Claves de API y facturación

Recarga el saldo de API después de un 402

Primeros pasos

Krea 3

Krea 2

Conceptos básicos

Ejemplos de código

Tutoriales

Errores y depuración

Errores en la solicitud y jobs fallidos

Cuerpos de respuesta

Envía `Accept: application/json`

Validación (`422`)

Campos eliminados y obsoletos (`422`)

Modelos retirados (`410`)

Códigos de estado

`400`

`401`

`402` Pago requerido

`403`

`404`

`405`

`413` Carga demasiado grande

Descargas de entradas

`429` de concurrencia

API de operaciones de Agent

`error.code` de jobs fallidos

Depuración

Próximos pasos

Ciclo de vida de un job

Webhooks

Límites de tasa

Claves de API y facturación

​Errores en la solicitud y jobs fallidos

​Cuerpos de respuesta

​Envía Accept: application/json

​Validación (422)

​Campos eliminados y obsoletos (422)

​Modelos retirados (410)

​Códigos de estado

​400

​401

​402 Pago requerido

​403

​404

​405

​413 Carga demasiado grande

​Descargas de entradas

​429 de concurrencia

​API de operaciones de Agent

​error.code de jobs fallidos

​Depuración

​Próximos pasos

Ciclo de vida de un job

Webhooks

Límites de tasa

Claves de API y facturación

Errores en la solicitud y jobs fallidos

Cuerpos de respuesta

Envía `Accept: application/json`

Validación (`422`)

Campos eliminados y obsoletos (`422`)

Modelos retirados (`410`)

Códigos de estado

`400`

`401`

`402` Pago requerido

`403`

`404`

`405`

`413` Carga demasiado grande

Descargas de entradas

`429` de concurrencia

API de operaciones de Agent

`error.code` de jobs fallidos

Depuración

Próximos pasos