Erros e depuração

Uma chamada pode falhar em dois sítios. O pedido pode ser rejeitado de imediato com um erro HTTP, ou pode ser aceite e terminar mais tarde com status: "failed". As tarefas falhadas e canceladas não são faturadas. Só paga pelas tarefas concluídas. Numa node app, a tarefa da própria app nunca é faturada. Cada nó de geração ou de LLM é cobrado quando a sua própria tarefa é concluída. Uma falha não cancela nós paralelos nem outros ramos, por isso um nó que seja concluído depois de a app já ter falhado também é cobrado, e essas cobranças não são reembolsadas. Um nó que falhe, seja cancelado ou nunca chegue a começar não é cobrado. Consulte Chaves de API e faturação.

Erros no momento do pedido e tarefas falhadas

Os erros no momento do pedido devolvem um estado 4xx ou 5xx. Não é criada nenhuma tarefa. Leia o corpo conforme descrito abaixo. As tarefas falhadas devolvem um estado de sucesso no momento da submissão. Consulte GET /jobs/{id} ou aguarde um webhook. Quando a tarefa termina, status é "failed" e a falha está no objeto error de nível superior. Não leia result numa tarefa falhada: é omitido (ou null). Só contém o resultado quando status é "completed". Uma tarefa cancelled não tem result nem error. Ramifique a lógica com base em error.code. message pode ser omitido e, para provider_error e internal, é texto livre do fornecedor. Não faça parsing de message.

if (job.status === "failed") {
  switch (job.error?.code ?? "internal") {
    case "content_policy":
    case "model_unavailable":
      // Repetir o mesmo pedido muito provavelmente voltará a falhar. Altere o input ou o modelo.
      break;
    case "insufficient_balance":
      // Carregue o saldo de API e depois submeta novamente.
      break;
    default:
      // timeout, auto_cancelled, provider_error, internal, node_app_node_failed,
      // ou um código desconhecido: submeta novamente com backoff.
  }
}

Corpos de resposta

Em generate, jobs, assets, styles e node apps, leia message ?? error quando o corpo é JSON. Um destes dois campos contém o resumo. Alguns corpos 5xx não são JSON, incluindo um 502 cujo corpo é o texto simples error code: 502. Faça o parsing de forma defensiva: se o corpo não for JSON, ramifique com base no estado HTTP. A maioria das falhas usa { "message": "..." }, por vezes com campos adicionais (limit, jobType, modelAccessDenial). O JSON inválido e alguns handlers abaixo usam { "error": "..." } em alternativa. Os endpoints MCP, como /mcp, devolvem erros JSON-RPC, { "jsonrpc", "id", "error": { "code", "message" } }, e não os corpos HTTP descritos nesta página.

Envie `Accept: application/json`

Sem Accept: application/json, alguns erros são devolvidos como uma página HTML e um parser de JSON vai falhar.

Os erros { "message" }, incluindo 401 e 404, são JSON quando Accept é application/json ou */*. Quando Accept está ausente, ou é text/html, esses estados são uma página HTML (Content-Type: text/html) e um parser de JSON vai falhar. Isto é relevante para clientes que não enviam nenhum cabeçalho Accept. O urllib do Python é um deles. O curl envia Accept: */* por predefinição, e o fetch do Node também, pelo que ambos recebem JSON, a menos que substitua Accept. Os pedidos não autenticados a POST /generate/..., GET /jobs/{id}, GET /styles e GET /assets devolvem 401 {"message":"Unauthorized"} para */* e application/json, e uma página HTML quando Accept está ausente ou é text/html. Um GET /jobs/{id} autenticado para um id desconhecido faz o mesmo com o estado: 404 JSON {"message":"Job not found or unauthorized"} quando Accept pede JSON, e 404 text/html quando Accept está ausente. O JSON inválido (400) e a validação (422) usam { "error" } e continuam a ser JSON mesmo quando Accept está ausente. O mesmo acontece com o 422 de campo removido, o 410 de fim de vida, o 402 de Zero Data Retention, as respostas { "error" } das node apps e os erros mapeados da API de operações do Agent. Os 402 e 429 resultantes da admissão de uma tarefa POST /generate/... também são JSON, incluindo com um Accept de navegador. Os 413 e 500 usam { "message" } e seguem Accept, tal como 401 e 404.

Validação (`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 lista todos os problemas. field é o caminho unido com . ("image_style_references.0.url"). Os erros ao nível do objeto usam uma string vazia, como acontece com a chave desconhecida acima. Várias chaves desconhecidas produzem Unrecognized keys: ... e o mesmo field vazio. expected só é adicionado quando code é "invalid_type". Um cabeçalho X-Webhook-URL inválido usa este mesmo 422. GET /jobs com parâmetros de consulta inválidos também devolve este 422. Não é um 400. Uma verificação de input de Zero Data Retention que falhe dentro da ferramenta devolve 422 com a explicação em message (o formato { "message" }, por isso Accept é relevante). Consulte Zero Data Retention.

Campos removidos e descontinuados (`422`)

O campo removido batchSize / batch_size usa um 422 diferente. Não existe uma matriz 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 é removido da mesma forma. field é o nome que tiver enviado. Um alias de campo descontinuado usa reason "deprecated_field" ou "conflicting_fields", além de replacement, sunset_date e migration_url quando aplicável. Ramifique com base em error e reason. A frase a mostrar a uma pessoa é message.

Modelos em fim de vida (`410`)

Um modelo que já passou a data de fim de vida devolve 410 com Deprecation: true e um cabeçalho Sunset (uma data 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 é o valor estável "model_unavailable". replacement e migration_url são omitidos quando não existe uma substituição recomendada. Repetir o pedido com o mesmo modelo continuará a devolver 410. Mude para replacement quando estiver definido e consulte Descontinuações. Um modelo descontinuado mas ainda ativo envia Deprecation e Sunset em todas as respostas, incluindo erros. Usar um alias de campo descontinuado faz o mesmo, incluindo no seu próprio 422. Quando existe um guia de migração, é também enviado um cabeçalho Link: <migration_url>; rel="deprecation".

Códigos de estado

Estado	Significado
`400`	Um corpo de generate não é JSON válido, um URL de input de uma node app não pôde ser usado, ou os parâmetros de assets ou node apps são inválidos. O JSON inválido no execute de node apps é `500`.
`401`	As credenciais estão em falta ou são inválidas.
`402`	O pedido foi recusado antes de uma tarefa começar. Consulte 402.
`403`	O autor da chamada está autenticado mas não tem permissão para usar este recurso.
`404`	Nenhuma rota correspondeu, o caminho do modelo é desconhecido ou não está disponível para si, ou falta uma tarefa, asset, style ou node app.
`405`	O método HTTP não é permitido para este caminho.
`410`	O modelo chegou ao fim de vida. Consulte Modelos em fim de vida.
`413`	O corpo do pedido é demasiado grande. Consulte 413.
`422`	A validação falhou, foi enviado um campo removido ou descontinuado, ou um input foi rejeitado de forma permanente.
`429`	Acima do limite de concorrência e a tarefa não pode entrar em backlog. O limite é aproximado.
`500`	Erro de servidor não tratado. `{ "message": "Internal Error" }`. Sem texto da exceção. Segue `Accept`.
`502`, `504`	Pode repetir. Um `502` chega como texto simples da Cloudflare `error code: 502`, e não como JSON, por isso ramifique com base no código de estado. O `504` também pode ser texto simples. Consulte Downloads de input.

`400`

O JSON inválido em generate é sempre JSON, sem ser necessário nenhum cabeçalho Accept:

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

O execute de node apps usa { "error" } para um URL de input que não consegue usar: Invalid URL for input "<key>", ou Failed to download URL for <key>: …. A mensagem de download abrange também falhas temporárias, por isso, ao contrário de generate (consulte Downloads de input), uma falha de download numa node app é sempre 400. Repita uma vez se o URL for válido. O JSON inválido em POST /node-apps/{id}/execute não é o 400 de generate acima. Torna-se um 500 { "message": "Internal Error" }, sem texto da exceção, e segue Accept. Outras respostas 400 em assets e node apps são { "message": "..." } com uma breve explicação, por exemplo No file provided num upload pré-assinado ou Invalid pagination parameters nas versões de node apps. Um upload de asset falhado transmite o estado do serviço de upload (400, 401, 404 ou 500) e pode colocar o texto da resposta deste em message. Esse texto é por vezes uma string JSON. Os parâmetros de consulta inválidos em GET /jobs são 422, não 400.

`401`

Generate, jobs, assets, styles e node apps:

{ "message": "Unauthorized" }

Os uploads pré-assinados devolvem { "message": "Presigned upload URL expired" } ou { "message": "Invalid presigned upload URL" }.

`402` Pagamento necessário

Para um cliente faturado pela API (uma chave de API, ou MCP com uma chave de API) cujo saldo de API não cubra a tarefa:

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

Carregue saldo em krea.ai/app/api/ ↗. As tarefas em curso terminam. Consulte Chaves de API e faturação. Outros valores de message de 402 na API pública:

`message`	Quando
`This tool is not available on your current plan.`	O seu plano ou workspace não permite tarefas simultâneas para este modelo.
`MEMBER_USAGE_LIMIT_REACHED`	O plano aplica limites de utilização por membro e o orçamento deste membro seria excedido.
`WORKSPACE_USAGE_LIMIT_REACHED`	O plano aplica limites de utilização por membro e o orçamento da workspace seria excedido.
`MEMBER_LIMIT_VIOLATION`	A workspace tem mais membros do que o seu plano permite.
`K3_ULTRA_ACCESS_REQUIRED`	Krea 3 com `thinking_mode` `"ultra"` (ou o antigo `"max"`) e imagens de referência, num plano sem Krea 3 Ultra. Sem imagens de referência, o Ultra é executado como `"fast"`.
`ENHANCER_RESOLUTION_LIMIT_REACHED`	Um upscale é maior do que o plano gratuito permite.

Uma chamada a generate com Zero Data Retention numa workspace que não o tem ativado devolve este corpo, sempre em JSON:

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

A API de operações do Agent usa os seus próprios corpos 402. Esses recorrem ao saldo de computação da workspace, e não ao saldo de API.

`403`

`message` ou `error`	Quando
`Use an API key or a plugin session`	Realtime, chamado sem uma chave de API nem uma sessão OAuth ou de plugin. `{ "message" }`.
`This endpoint needs a workspace service API key`	Usage API, a credencial não é uma chave de API de serviço da workspace. `{ "message" }`.
`Your plan is not entitled to the usage API`	Usage API, o plano não dá direito a ela. `{ "message" }`.
`FEATURE_RESTRICTED`	Recusa pela política de modelos. O corpo inclui também `modelAccessDenial`. `{ "message" }`.
`MODEL_ACCESS_REQUIRED`	O modelo é apenas interno. `{ "message" }`.
`This node app cannot be used via the API.`	Execute de node apps. `{ "error" }`, sempre JSON.
`Free users cannot run node apps`	Execute de node apps numa workspace com plano gratuito. `{ "message" }`.
`You do not own this style`	Alterar ou partilhar um style de que não é proprietário. `{ "message" }`.

`404`

Todos os 404 são { "message" }, por exemplo um id de tarefa desconhecido:

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

A ausência do cabeçalho Accept torna-os HTML, exceto o Endpoint not found para um modelo que a sua chave ou o seu plano não pode usar, que é sempre JSON. Um GET /jobs/{id} autenticado para um id desconhecido sem Accept é 404 text/html.

`message`	Quando
`Not Found`	Nenhuma rota correspondeu ao caminho.
`Endpoint not found`	Um caminho de modelo em `/generate` que é desconhecido, ou que esta chave de API ou plano não pode usar.
`Job not found or unauthorized`	Id de tarefa em falta ou inválido, incluindo `DELETE /jobs/{id}`.
`Asset not found`	Asset em falta.
`Style not found`	Style em falta. Alterar ou partilhar um de que não é proprietário devolve `Style not found or you are not the owner`.
`Node app not found`	Node app em falta.
`Workspace not found`	Usage API, a workspace não existe.

Uma operação do Agent desconhecida também é 404 { "message": "Endpoint not found" }, e não o formato { "error", "code" } do Agent.

`405`

O corpo é texto simples sem cabeçalho Content-Type, não JSON, incluindo quando Accept é application/json. O texto é o método seguido de method not allowed, por exemplo GET method not allowed. Um cabeçalho Allow lista os métodos que o caminho aceita.

`413` Payload demasiado grande

Um corpo de pedido demasiado grande é rejeitado com 413. Quando vem da própria API, o corpo segue Accept:

{ "message": "Payload Too Large" }

Um corpo muito grande pode ser rejeitado antes de chegar à API, com uma página HTML 413. Não envie ficheiros inline. Carregue o ficheiro com POST /assets e passe o URL devolvido no pedido de geração.

Downloads de input

Um servidor que devolva 404 ou 410 resulta num 422 permanente. O corpo é JSON, e Accept é relevante:

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

Um 410 do servidor usa a mesma frase com 410. Outras rejeições permanentes usam Input file rejected: …. Uma falha de download que se pode repetir é 502 ou 504. Ramifique com base no código de estado, não no corpo, e repita.

Estado	O que recebe	Repetir?
`422`	JSON `{ "message": "Input file rejected: fetching <url> returned HTTP 404" }` quando o servidor devolve `404`. Um `410` do servidor usa a mesma frase com `410`.	Não. A falha é permanente.
`502`	Texto simples da Cloudflare `error code: 502`, com `Content-Type: text/plain; charset=UTF-8`. Confirmado quando o servidor do ficheiro devolve `503`, `500` ou `429`, e quando o domínio não é resolvido.	Sim. Ramifique com base no código de estado.
`504`	Não testado em produção. Também pode chegar como texto simples da Cloudflare.	Sim. Ramifique com base no código de estado.

Um 502 que se repete constantemente para o mesmo URL significa provavelmente que o URL está bloqueado ou danificado. Altere o URL. As falhas de conversão na exportação 3D também são 502. Esse caminho não foi testado em produção, por isso o corpo também pode chegar como texto simples da Cloudflare error code: 502. Ramifique com base no código de estado e repita. Um 502 que se repete constantemente para o mesmo URL de modelo significa provavelmente que o URL está bloqueado ou danificado.

`429` de concorrência

Quando a tarefa não pode entrar em backlog, um pedido acima do limite de concorrência pode ser rejeitado com 429 e Content-Type: application/json:

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

limit é o seu limite de concorrência para este tipo de tarefa. É contabilizado por utilizador, não por workspace. É aproximado: um pico curto pode ser aceite acima dele, por isso não conte que seja o pedido limit + 1 a falhar. jobType é uma categoria interna de tarefa, não o caminho público do modelo. Não ramifique com base nele. O Krea 2 também pode devolver apenas { "message": "CONCURRENCY_LIMIT_REACHED" }, sem limit nem jobType, quando a sua fila partilhada está cheia. Esse não é o seu limite. Aguarde e repita. O backlog só está ativo quando o plano o inclui (Pro e superiores), o modelo o suporta e o pedido não usa Zero Data Retention. De momento, os pedidos ao Krea 2 não entram em backlog em nenhum plano, por isso devolvem 429 acima do limite. Quando está ativo, a tarefa adicional é aceite com status: "backlogged" e começa assim que houver uma vaga livre. Não existe um limite separado para o backlog. Consulte Limites de taxa. A API não envia Retry-After nem X-RateLimit-*. A resposta inclui cf-ray. Perante um 429, repita com backoff exponencial depois de as tarefas em curso terminarem (consulte GET /jobs/{id} ou use um webhook). Se uma conclusão posterior esgotar o saldo, as tarefas que ainda estejam no backlog falham com error.code "insufficient_balance". Trata-se de uma tarefa falhada, não de um HTTP 402. Essas tarefas não enviam webhook, por isso consulte GET /jobs/{id} para as tarefas em backlog.

API de operações do Agent

POST /agent/{operation} e GET /agent/session/{sessionId} devolvem { "error", "code"?, "allowedModels"? }. Apenas error é obrigatório. allowedModels está em camelCase. Um turno que falhe depois de ter sido aceite aparece como status: "failed" na sessão, e não como um destes erros HTTP. Consulte Agent.

Estado	Corpo
`400`	`{ "error": "Invalid JSON body" }`
`401`	`{ "error": "Unauthorized" }`
`402`	`{ "error": "Insufficient compute balance for an Agent turn", "code": "compute_limit" }`, ou `{ "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`	Operação desconhecida: `{ "message": "Endpoint not found" }`. Caso contrário, `{ "error": "Session not found or not accessible", "code": "not_found" }`, ou `{ "error": "<file reference error>", "code": "attachment_not_found" }`.
`409`	`{ "error": "...", "code": "conflict" }`.
`422`	Input inválido: `{ "error": "Validation failed", "details": [...] }`, como em Validação. Os outros erros mapeados são `{ "error": "<message>" }` mais `code` quando existe. Uma app de desktop desligada não tem `code`; a mensagem começa por `That desktop app is not connected`.

Um código de erro do Agent não reconhecido continua a ser 422 com { "error", "code" }. O 404 de operação desconhecida e um 500 não tratado usam { "message" } e seguem Accept.

`error.code` de tarefas falhadas

GET /jobs e GET /jobs/{id} só definem error quando status é "failed". Não existe um result utilizável:

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

Ramifique com base em error.code. Nunca faça parsing de message.message pode ser omitido. As mensagens de provider_error e internal são texto livre, e uma mensagem internal pode ser texto em bruto do fornecedor, como failed to download media from the provided URL. Trate qualquer code que não reconheça como internal.

`code`	`message`	O que fazer
`content_policy`	`Krea's moderation systems rejected the generation.` ou `An external provider's moderation systems rejected the generation.`	Altere o prompt ou os inputs. O mesmo pedido será muito provavelmente rejeitado de novo.
`timeout`	`An external provider did not complete the generation in sufficient time.`	Repita a tarefa.
`insufficient_balance`	Omitido. Uma node app pode, em vez disso, devolver `You are out of compute units. Add more compute units to continue running this node app.`	Carregue saldo e submeta novamente. Esta tarefa foi aceite anteriormente; a chamada HTTP não devolveu `402`.
`auto_cancelled`	`Job repeatedly failed healthchecks and was automatically cancelled.`	Submeta a tarefa novamente.
`model_unavailable`	Normalmente o texto do próprio fornecedor. `The provider retired this model. It no longer accepts new generations.` quando não existe nenhum.	Deixe de chamar este modelo. Use a substituição indicada em Descontinuações, quando existir.
`provider_error`	Normalmente o texto do próprio fornecedor.	Repita com backoff.
`internal`	Texto livre, ou omitido.	Repita mais tarde. Indique o `job_id` se contactar o suporte.
`node_app_node_failed`	`Node "<type>" failed: <detail>` ou `Node "<type>" failed.`	Leia `message`. Se o nó encontrou um problema temporário, como um timeout, execute a app novamente. Caso contrário, corrija primeiro esse nó. A tarefa da própria app nunca é faturada. Cada nó de geração ou de LLM é cobrado quando a sua própria tarefa é concluída. Uma falha não cancela nós paralelos nem outros ramos, por isso um nó que seja concluído depois de a app já ter falhado também é cobrado, e essas cobranças não são reembolsadas. Um nó que falhe, seja cancelado ou nunca chegue a começar não é cobrado. O id e o tipo do nó não constam da tarefa pública.

As entregas de webhook para uma tarefa falhada usam o mesmo objeto de tarefa, incluindo error. Uma entrega de cancelamento não tem error. Um payload com mais de 256 KiB não é enviado, e não são feitas mais entregas para essa tarefa, por isso consulte GET /jobs/{id} em alternativa. Verifique a assinatura antes de confiar no corpo. Consulte Webhooks.

Depuração

Não existe um cabeçalho de id de pedido da Krea. Todas as respostas incluem o cabeçalho cf-ray da Cloudflare. Não é enviado nenhum cabeçalho Retry-After nem X-RateLimit-*. Quando escrever para support@krea.ai, inclua:

O job_id, quando a chamada criou ou referiu uma tarefa
A hora e o endpoint
Para um erro no momento do pedido, o valor de cf-ray

Access-Control-Allow-Origin é *. Em generate, jobs, assets, styles e node apps, Access-Control-Expose-Headers não está definido, por isso o fetch do navegador não consegue ler cf-ray, Deprecation nem Sunset. Copie cf-ray do registo de rede, ou a partir de um cliente do lado do servidor. Em qualquer resposta, verifique Deprecation e Sunset antes de o modelo deixar de aceitar chamadas. Consulte Descontinuações.

Próximos passos

Ciclo de vida das tarefas

Consulte o estado até a tarefa ser concluída, falhar ou ser cancelada

Webhooks

Verifique a assinatura numa entrega de tarefa falhada

Limites de taxa

Quando as tarefas adicionais entram em backlog e quando devolvem 429

Chaves de API e faturação

Carregue o saldo de API após um 402

Começar

Krea 3

Krea 2

Conceitos principais

Exemplos de código

Tutoriais

Erros e depuração

Erros no momento do pedido e tarefas falhadas

Corpos de resposta

Envie `Accept: application/json`

Validação (`422`)

Campos removidos e descontinuados (`422`)

Modelos em fim de vida (`410`)

Códigos de estado

`400`

`401`

`402` Pagamento necessário

`403`

`404`

`405`

`413` Payload demasiado grande

Downloads de input

`429` de concorrência

API de operações do Agent

`error.code` de tarefas falhadas

Depuração

Próximos passos

Ciclo de vida das tarefas

Webhooks

Limites de taxa

Chaves de API e faturação

​Erros no momento do pedido e tarefas falhadas

​Corpos de resposta

​Envie Accept: application/json

​Validação (422)

​Campos removidos e descontinuados (422)

​Modelos em fim de vida (410)

​Códigos de estado

​400

​401

​402 Pagamento necessário

​403

​404

​405

​413 Payload demasiado grande

​Downloads de input

​429 de concorrência

​API de operações do Agent

​error.code de tarefas falhadas

​Depuração

​Próximos passos

Ciclo de vida das tarefas

Webhooks

Limites de taxa

Chaves de API e faturação

Erros no momento do pedido e tarefas falhadas

Corpos de resposta

Envie `Accept: application/json`

Validação (`422`)

Campos removidos e descontinuados (`422`)

Modelos em fim de vida (`410`)

Códigos de estado

`400`

`401`

`402` Pagamento necessário

`403`

`404`

`405`

`413` Payload demasiado grande

Downloads de input

`429` de concorrência

API de operações do Agent

`error.code` de tarefas falhadas

Depuração

Próximos passos