Erros e depuração

Uma chamada pode falhar em dois momentos. A requisição pode ser rejeitada imediatamente com um erro HTTP, ou pode ser aceita e depois terminar com status: "failed". Jobs que falham ou são cancelados não são cobrados. Você paga apenas pelos jobs concluídos. Em um node app, o job do próprio app nunca é cobrado. Cada nó de geração ou de LLM é cobrado quando o seu próprio job é concluído. Uma falha não cancela nós paralelos nem outras ramificações, então um nó concluído depois que o app já falhou também é cobrado, e essas cobranças não são reembolsadas. Um nó que falha, é cancelado ou nunca começa não é cobrado. Veja API Keys & Billing.

Erros no momento da requisição e jobs com falha

Erros no momento da requisição retornam um status 4xx ou 5xx. Nenhum job é criado. Leia o corpo conforme descrito abaixo. Jobs com falha retornam um status de sucesso no envio. Faça polling em GET /jobs/{id} ou aguarde um webhook. Quando o job termina, status é "failed" e a falha fica no objeto error de nível superior. Não leia result em um job com falha: ele é omitido (ou null). Ele só contém a saída quando status é "completed". Um job cancelled não tem nem result nem error. Use error.code para decidir o que fazer. message pode ser omitido e, para provider_error e internal, é um texto livre do provedor. Não faça parsing de message.

if (job.status === "failed") {
  switch (job.error?.code ?? "internal") {
    case "content_policy":
    case "model_unavailable":
      // Repetir a mesma requisição provavelmente falhará de novo. Altere a entrada ou o modelo.
      break;
    case "insufficient_balance":
      // Adicione saldo de API e envie novamente.
      break;
    default:
      // timeout, auto_cancelled, provider_error, internal, node_app_node_failed
      // ou um código desconhecido: envie novamente com backoff.
  }
}

Corpos de resposta

Em generate, jobs, assets, styles e node apps, leia message ?? error quando o corpo for JSON. Um desses dois campos traz 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, decida com base no status HTTP. A maioria das falhas usa { "message": "..." }, às vezes com campos extras (limit, jobType, modelAccessDenial). JSON inválido e alguns handlers abaixo usam { "error": "..." } em vez disso. Endpoints MCP como /mcp retornam erros JSON-RPC, { "jsonrpc", "id", "error": { "code", "message" } }, e não os corpos HTTP desta página.

Envie `Accept: application/json`

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

Erros { "message" }, incluindo 401 e 404, são JSON quando Accept é application/json ou */*. Quando Accept está ausente, ou é text/html, esses status retornam uma página HTML (Content-Type: text/html) e um parser de JSON vai falhar. Isso importa para clientes que não enviam o cabeçalho Accept. O urllib do Python é um deles. O curl envia Accept: */* por padrão, e o fetch do Node também, então ambos recebem JSON, a menos que você sobrescreva Accept. POST /generate/..., GET /jobs/{id}, GET /styles e GET /assets sem autenticação retornam 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 status: 404 JSON {"message":"Job not found or unauthorized"} quando Accept pede JSON, e 404 text/html quando Accept está ausente. JSON inválido (400) e validação (422) usam { "error" } e continuam em JSON mesmo quando Accept está ausente. O mesmo vale para o 422 de campo removido, o 410 de modelo descontinuado, o 402 de Zero Data Retention, as respostas { "error" } de node apps e os erros mapeados da API de operações do Agent. Os 402 e 429 na admissão de um job POST /generate/... também são JSON, inclusive para um Accept de navegador. 413 e 500 usam { "message" } e seguem o Accept, assim 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 por . ("image_style_references.0.url"). Erros no nível do objeto usam uma string vazia, como na 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 esse mesmo 422. GET /jobs com parâmetros de consulta inválidos também retorna esse 422. Não é um 400. Uma verificação de entrada de Zero Data Retention que falha dentro da ferramenta retorna 422 com a explicação em message (o formato { "message" }, então o Accept importa). Veja Zero Data Retention.

Campos removidos e obsoletos (`422`)

O campo removido batchSize / batch_size usa um 422 diferente. Não há array 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 você enviou. Um alias de campo obsoleto usa reason "deprecated_field" ou "conflicting_fields", além de replacement, sunset_date e migration_url quando se aplicam. Decida com base em error e reason. A frase a ser mostrada para uma pessoa é message.

Modelos descontinuados (`410`)

Um modelo que passou da data de descontinuação retorna 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 há substituto recomendado. Repetir com o mesmo modelo continuará retornando 410. Mude para replacement quando ele estiver definido e veja Descontinuações. Um modelo obsoleto, mas ainda ativo, envia Deprecation e Sunset em todas as respostas, incluindo erros. Usar um alias de campo obsoleto faz o mesmo, inclusive no seu próprio 422. Quando existe um guia de migração, um cabeçalho Link: <migration_url>; rel="deprecation" também é enviado.

Códigos de status

Status	Significado
`400`	Um corpo de generate não é JSON válido, uma URL de entrada de node app não pôde ser usada, ou os parâmetros de asset ou de node app são inválidos. JSON inválido no execute de node app é `500`.
`401`	As credenciais estão ausentes ou são inválidas.
`402`	A requisição foi recusada antes de um job começar. Veja 402.
`403`	O chamador 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 você, ou um job, asset, style ou node app não existe.
`405`	O método HTTP não é permitido para este caminho.
`410`	O modelo foi descontinuado. Veja Modelos descontinuados.
`413`	O corpo da requisição é grande demais. Veja 413.
`422`	A validação falhou, um campo removido ou obsoleto foi enviado, ou uma entrada foi rejeitada permanentemente.
`429`	Acima do limite de concorrência e o job não pode entrar em backlog. O limite é aproximado.
`500`	Erro de servidor não tratado. `{ "message": "Internal Error" }`. Sem texto de exceção. Segue o `Accept`.
`502`, `504`	Pode ser repetido. Um `502` chega como texto simples do Cloudflare `error code: 502`, não JSON, então decida com base no código de status. `504` também pode ser texto simples. Veja Downloads de entrada.

`400`

JSON inválido em generate é sempre JSON, sem precisar do cabeçalho Accept:

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

O execute de node app usa { "error" } para uma URL de entrada que não consegue usar: Invalid URL for input "<key>" ou Failed to download URL for <key>: …. A mensagem de download também cobre falhas temporárias, então, ao contrário de generate (veja Downloads de entrada), uma falha de download em node app é sempre 400. Tente novamente uma vez se a URL for válida. JSON inválido em POST /node-apps/{id}/execute não é o 400 de generate acima. Ele vira um 500 { "message": "Internal Error" }, sem texto de exceção, e segue o Accept. Outras respostas 400 em assets e node apps são { "message": "..." } com uma explicação curta, por exemplo No file provided em um upload pré-assinado ou Invalid pagination parameters nas versões de node app. Um upload de asset com falha repassa o status do serviço de upload (400, 401, 404 ou 500) e pode colocar o texto da resposta em message. Esse texto às vezes é uma string JSON. 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" }

Uploads pré-assinados retornam { "message": "Presigned upload URL expired" } ou { "message": "Invalid presigned upload URL" }.

Pagamento necessário (`402`)

Para um cliente cobrado via API (uma chave de API, ou MCP usando uma chave de API) cujo saldo de API não cobre o job:

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

Adicione saldo em krea.ai/app/api/ ↗. Jobs em andamento são concluídos. Veja API Keys & Billing. Outros valores de message para 402 na API pública:

`message`	Quando
`This tool is not available on your current plan.`	Seu plano ou workspace não permite jobs simultâneos para este modelo.
`MEMBER_USAGE_LIMIT_REACHED`	O plano aplica limites de uso por membro e o orçamento deste membro seria excedido.
`WORKSPACE_USAGE_LIMIT_REACHED`	O plano aplica limites de uso por membro e o orçamento do workspace seria excedido.
`MEMBER_LIMIT_VIOLATION`	O workspace tem mais membros do que o plano permite.
`K3_ULTRA_ACCESS_REQUIRED`	Krea 3 com `thinking_mode` `"ultra"` (ou o legado `"max"`) e referências de imagem, em um plano sem Krea 3 Ultra. Sem referências de imagem, o Ultra é executado como `"fast"`.
`ENHANCER_RESOLUTION_LIMIT_REACHED`	Um upscale é maior do que o plano gratuito permite.

Uma chamada de generate com Zero Data Retention em um workspace que não tem o recurso ativado retorna este corpo, sempre em JSON:

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

A API de operações do Agent usa seus próprios corpos 402. Eles consomem o saldo de computação do workspace, não o saldo de API.

`403`

`message` ou `error`	Quando
`Use an API key or a plugin session`	Realtime, chamado sem uma chave de API ou 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 do workspace. `{ "message" }`.
`Your plan is not entitled to the usage API`	Usage API, o plano não dá direito ao recurso. `{ "message" }`.
`FEATURE_RESTRICTED`	Negação pela política do modelo. O corpo também inclui `modelAccessDenial`. `{ "message" }`.
`MODEL_ACCESS_REQUIRED`	O modelo é apenas interno. `{ "message" }`.
`This node app cannot be used via the API.`	Execute de node app. `{ "error" }`, sempre JSON.
`Free users cannot run node apps`	Execute de node app em um workspace do plano gratuito. `{ "message" }`.
`You do not own this style`	Alterar ou compartilhar um style que não é seu. `{ "message" }`.

`404`

Todo 404 é { "message" }, por exemplo um id de job desconhecido:

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

A ausência do cabeçalho Accept faz com que esses erros sejam HTML, exceto o Endpoint not found para um modelo que sua chave ou 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 job ausente ou inválido, incluindo `DELETE /jobs/{id}`.
`Asset not found`	Asset inexistente.
`Style not found`	Style inexistente. Alterar ou compartilhar um que não é seu retorna `Style not found or you are not the owner`.
`Node app not found`	Node app inexistente.
`Workspace not found`	Usage API, o workspace não existe.

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

`405`

O corpo é texto simples sem cabeçalho Content-Type, não JSON, inclusive 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.

Payload grande demais (`413`)

Um corpo de requisição grande demais é rejeitado com 413. Vindo da própria API, o corpo segue o Accept:

{ "message": "Payload Too Large" }

Um corpo muito grande pode ser rejeitado antes de chegar à API, com uma página 413 em HTML. Não envie arquivos inline. Faça o upload do arquivo com POST /assets e passe a URL retornada na requisição de generate.

Downloads de entrada

Um host que retorna 404 ou 410 gera um 422 permanente. O corpo é JSON, e o Accept importa:

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

Um 410 do host usa a mesma frase com 410. Outras rejeições permanentes usam Input file rejected: …. Uma falha de download que pode ser repetida é 502 ou 504. Decida com base no código de status, não no corpo, e tente novamente.

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

Um 502 que se repete para a mesma URL provavelmente significa que a URL está bloqueada ou quebrada. Troque a URL. Falhas de conversão na exportação 3D também são 502. Esse caminho não foi testado em produção, então o corpo também pode chegar como texto simples do Cloudflare error code: 502. Decida com base no código de status e tente novamente. Um 502 que se repete para a mesma URL de modelo provavelmente significa que a URL está bloqueada ou quebrada.

`429` de concorrência

Quando o job não pode entrar em backlog, uma requisição acima do limite de concorrência pode ser rejeitada com 429 e Content-Type: application/json:

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

limit é o seu limite de concorrência para esse tipo de job. Ele é contado por usuário, não por workspace. É aproximado: uma rajada curta pode ser aceita acima dele, então não conte que a requisição limit + 1 será a que falha. jobType é uma categoria interna de job, não o caminho público do modelo. Não tome decisões com base nele. O Krea 2 também pode retornar apenas { "message": "CONCURRENCY_LIMIT_REACHED" }, sem limit nem jobType, quando sua fila compartilhada está cheia. Esse não é o seu limite. Aguarde e tente novamente. O backlog só fica ativo quando o plano o inclui (Pro e superiores), o modelo oferece suporte e a requisição não é de Zero Data Retention. No momento, requisições do Krea 2 não entram em backlog em nenhum plano, então retornam 429 acima do limite. Quando ele está ativo, o job extra é aceito com status: "backlogged" e começa assim que houver uma vaga livre. Não há um limite separado para o backlog. Veja Limites de Taxa. A API não envia Retry-After nem X-RateLimit-*. A resposta inclui cf-ray. Ao receber 429, tente novamente com backoff exponencial depois que os jobs em andamento terminarem (faça polling em GET /jobs/{id} ou use um webhook). Se uma conclusão posterior esgotar o saldo, os jobs que ainda estão no backlog falham com error.code "insufficient_balance". Isso é um job com falha, não um HTTP 402. Esses jobs não enviam webhook, então faça polling em GET /jobs/{id} para jobs em backlog.

API de operações do Agent

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

Status	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`	Entrada inválida: `{ "error": "Validation failed", "details": [...] }`, como em Validação. Outros erros mapeados são `{ "error": "<message>" }` mais `code` quando existe um. Um app desktop desconectado não tem `code`; a mensagem começa com `That desktop app is not connected`.

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

`error.code` de jobs com falha

GET /jobs e GET /jobs/{id} definem error apenas quando status é "failed". Não há result utilizável:

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

Decida 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 o texto bruto do provedor, como failed to download media from the provided URL. Trate qualquer code que você 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 as entradas. A mesma requisição provavelmente será rejeitada de novo.
`timeout`	`An external provider did not complete the generation in sufficient time.`	Tente o job novamente.
`insufficient_balance`	Omitido. Um node app pode retornar `You are out of compute units. Add more compute units to continue running this node app.`	Adicione saldo e envie novamente. Este job foi aceito antes; a chamada HTTP não retornou `402`.
`auto_cancelled`	`Job repeatedly failed healthchecks and was automatically cancelled.`	Envie o job novamente.
`model_unavailable`	Geralmente o próprio texto do provedor. `The provider retired this model. It no longer accepts new generations.` quando não há texto.	Pare de chamar este modelo. Use o substituto indicado em Descontinuações, quando houver.
`provider_error`	Geralmente o próprio texto do provedor.	Tente novamente com backoff.
`internal`	Texto livre, ou omitido.	Tente novamente mais tarde. Informe o `job_id` se entrar em contato com 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 o app novamente. Caso contrário, corrija esse nó primeiro. O job do próprio app nunca é cobrado. Cada nó de geração ou de LLM é cobrado quando o seu próprio job é concluído. Uma falha não cancela nós paralelos nem outras ramificações, então um nó concluído depois que o app já falhou também é cobrado, e essas cobranças não são reembolsadas. Um nó que falha, é cancelado ou nunca começa não é cobrado. O id e o tipo do nó não aparecem no job público.

As entregas de webhook de um job com falha usam o mesmo objeto de job, incluindo error. Uma entrega de cancelamento não tem error. Um payload maior que 256 KiB não é enviado, e nenhuma outra entrega é feita para esse job, então faça polling em GET /jobs/{id}. Verifique a assinatura antes de confiar no corpo. Veja Webhooks.

Depuração

Não existe um cabeçalho de id de requisição da Krea. Toda resposta inclui o cabeçalho cf-ray do Cloudflare. Nenhum cabeçalho Retry-After ou X-RateLimit-* é enviado. Ao escrever para support@krea.ai, inclua:

O job_id, quando a chamada criou ou referenciou um job
O horário e o endpoint
Para um erro no momento da requisição, o valor de cf-ray

Access-Control-Allow-Origin é *. Em generate, jobs, assets, styles e node apps, Access-Control-Expose-Headers não é definido, então o fetch do navegador não consegue ler cf-ray, Deprecation nem Sunset. Copie o cf-ray do log de rede ou de um cliente no servidor. Em qualquer resposta, verifique Deprecation e Sunset antes que o modelo pare de aceitar chamadas. Veja Descontinuações.

Próximos passos

Ciclo de vida do job

Faça polling do status até o job ser concluído, falhar ou ser cancelado

Webhooks

Verifique a assinatura em uma entrega de job com falha

Limites de taxa

Quando jobs extras entram em backlog e quando retornam 429

API Keys & Billing

Adicione saldo de API depois de um 402

Primeiros passos

Krea 3

Krea 2

Conceitos principais

Exemplos de código

Tutoriais

Erros e depuração

Erros no momento da requisição e jobs com falha

Corpos de resposta

Envie `Accept: application/json`

Validação (`422`)

Campos removidos e obsoletos (`422`)

Modelos descontinuados (`410`)

Códigos de status

`400`

`401`

Pagamento necessário (`402`)

`403`

`404`

`405`

Payload grande demais (`413`)

Downloads de entrada

`429` de concorrência

API de operações do Agent

`error.code` de jobs com falha

Depuração

Próximos passos

Ciclo de vida do job

Webhooks

Limites de taxa

API Keys & Billing

​Erros no momento da requisição e jobs com falha

​Corpos de resposta

​Envie Accept: application/json

​Validação (422)

​Campos removidos e obsoletos (422)

​Modelos descontinuados (410)

​Códigos de status

​400

​401

​Pagamento necessário (402)

​403

​404

​405

​Payload grande demais (413)

​Downloads de entrada

​429 de concorrência

​API de operações do Agent

​error.code de jobs com falha

​Depuração

​Próximos passos

Ciclo de vida do job

Webhooks

Limites de taxa

API Keys & Billing

Erros no momento da requisição e jobs com falha

Corpos de resposta

Envie `Accept: application/json`

Validação (`422`)

Campos removidos e obsoletos (`422`)

Modelos descontinuados (`410`)

Códigos de status

`400`

`401`

Pagamento necessário (`402`)

`403`

`404`

`405`

Payload grande demais (`413`)

Downloads de entrada

`429` de concorrência

API de operações do Agent

`error.code` de jobs com falha

Depuração

Próximos passos