KernosDevelopers
Sair
Erros
Referência

Erros

75 códigos de recusa. Toda recusa vem no envelope com ok: false, o error_code (estável: decida por ele), a frase em português para mostrar a uma pessoa, o field que causou a recusa e o trace_id para falar com a Kernos.

Para agentes e terminalEsta página em Markdown: /erros.mdÍndice das páginas: /llms.txt
Uma recusa
{
  "ok": false,
  "data": null,
  "error": "Este pedido (`order_ref` da mesma origem) já foi importado.",
  "error_code": "order_already_imported",
  "field": "order_ref",
  "trace_id": "…"
}

HTTP 400 · Pedido mal formado

invalid_active HTTP 400Filtro de situação inválido: use true ou false.
invalid_block_reason HTTP 400Recorte de bloqueio inválido: use any ou uma das razões declaradas no parâmetro.
invalid_idempotency_key HTTP 400Toda escrita pede o cabeçalho Idempotency-Key com um UUID.
invalid_limit HTTP 400limit fora da faixa: de 1 a 200.
invalid_offset HTTP 400offset inválido: um inteiro de zero para cima.
invalid_order HTTP 400Ordenação inválida: use um dos valores declarados no parâmetro.
invalid_policy HTTP 400Recorte de política inválido: use um dos valores declarados no parâmetro.
invalid_status HTTP 400Situação inválida para este filtro ou campo: use um dos valores declarados.
invalid_view HTTP 400Recorte inválido: use um dos valores declarados no parâmetro.
version_unknown HTTP 400A Kernos-Version pedida não existe. Use uma das versões declaradas no cabeçalho, ou não o mande.

HTTP 401 · Sem credencial válida

api_key_expired HTTP 401A chave venceu. Gire a chave no painel e use a nova.
api_key_wrong_environment HTTP 401A chave é do outro ambiente: ksk_test_ vai em https://stag.kernos.com.br, ksk_live_ em https://api.kernos.com.br.
unauthenticated HTTP 401Credencial ausente, inválida ou expirada.

HTTP 403 · Sem permissão

agent_token_out_of_scope HTTP 403O token de agente (kat_) só vale na porta MCP. Para a API, use o token de sessão ou uma chave de integração.
api_key_action_not_granted HTTP 403A chave não tem esta ação. Edite as ações da chave no painel.
api_key_out_of_scope HTTP 403A chave só vale nas rotas do contrato público.
depot_out_of_reach HTTP 403Quem chama não alcança o CD deste objeto. Peça alcance ao CD ou use outra credencial.
forbidden_role HTTP 403O papel de quem chama nesta empresa não permite esta ação.
module_not_subscribed HTTP 403A empresa não assina o módulo desta rota.
tenant_mismatch HTTP 403A credencial não pertence à empresa do endereço chamado.
tenant_unavailable HTTP 403A empresa está indisponível no momento.

HTTP 404 · Não encontrado

depot_not_found HTTP 404Não existe CD com esse depot_code nesta empresa.
dock_not_found HTTP 404A doca informada não existe neste CD.
not_found HTTP 404Não existe objeto com esse identificador nesta empresa.

HTTP 409 · Conflito

already_closed HTTP 409A associação já está encerrada; não há o que encerrar de novo.
ambiguous_identifier HTTP 409O valor é o SKU de um produto e o EAN de outro. Mande o identificador que não deixa dúvida (o id do produto).
depot_inactive HTTP 409O CD está fechado. Reabra o CD antes de mexer no que está dentro dele.
duplicate_ean HTTP 409Já existe produto com este EAN nesta empresa.
duplicate_sku HTTP 409Já existe produto com este SKU nesta empresa.
idempotency_key_reused HTTP 409Esta Idempotency-Key já foi usada com outro corpo. Gere uma chave nova para uma escrita nova.
nfe_already_received HTTP 409Esta NF-e já foi recebida. Use o recebimento que existe em vez de importar de novo.
no_active_depot HTTP 409A empresa não tem CD ativo; sem depot_code, não há CD a usar.
order_already_imported HTTP 409Este pedido (order_ref da mesma origem) já foi importado.
order_loaded HTTP 409O pedido tem volume carregado num envio: tire o volume do envio antes de cancelar.
order_not_open HTTP 409Um dos pedidos já está em outra onda ou já saiu.
other_depot HTTP 409A posição é de outro CD.
picking_face_exists HTTP 409O produto já tem posição de separação neste CD. Guarde como pulmão ou desenderece a separação antes.
product_in_use HTTP 409O produto ainda está endereçado. Retire das posições antes de desativar.
stock_not_reservable HTTP 409O disponível do CD (saldo menos o já reservado) não cobre alguma linha do pedido.

HTTP 422 · Não processável

empty_update HTTP 422O corpo não traz nenhum campo para atualizar.
fractional_qty HTTP 422Há item com quantidade fracionada, e o saldo conta unidades inteiras. Cadastre o item na unidade menor.
invalid_channel HTTP 422O canal não está no catálogo da Kernos: use o código de um canal (shopee, mercado_livre…) ou omita.
invalid_cursor HTTP 422O after não é um evento desta empresa. Use o next_after da consulta anterior; eventos com mais de 90 dias saem do anel.
invalid_ean HTTP 422O EAN tem de ter só dígitos, de 8 a 14 (EAN-8, UPC, EAN-13 ou GTIN-14).
invalid_event_type HTTP 422Um dos tipos não é um evento público. Use os nomes do contrato, separados por vírgula (shipment.dispatch,pix.paid).
invalid_grace HTTP 422A carência da troca do segredo vai de 0 a 168 horas.
invalid_kind HTTP 422Tipo de ordem de serviço inválido: use um dos valores declarados no campo.
invalid_move_origin HTTP 422Transferência precisa da posição de origem, além da de destino.
invalid_nfe_xml HTTP 422O arquivo não é o XML de uma NF-e autorizada que dê para ler (o DANFE em PDF não serve).
invalid_order_csv HTTP 422O arquivo não está no layout do pedido: cabeçalho order_ref;customer;product;qty;carrier_cnpj, um pedido por arquivo.
invalid_order_json HTTP 422O pedido não está no formato declarado no corpo da rota; o field diz qual campo.
invalid_origin HTTP 422A origem não está no catálogo da Kernos: use o código do parceiro que manda o pedido (bling, tiny…) ou omita.
invalid_params HTTP 422Um parâmetro está fora do formato declarado; o field diz qual.
invalid_place_kind HTTP 422Tipo de guarda inválido para esta parada.
invalid_priority HTTP 422Prioridade inválida: use um dos valores declarados no campo.
invalid_qty HTTP 422Quantidade inválida: um inteiro maior que zero.
invalid_scope HTTP 422Recontar o corredor inteiro só existe na ordem de contagem.
invalid_source HTTP 422Origem da leitura inválida: use um dos valores declarados no campo.
invalid_trait HTTP 422Um valor do item não vale: peso e medida são números maiores que zero.
invalid_value HTTP 422O texto traz caractere que não se aceita (nulo, U+0000). Tire-o e mande de novo.
invalid_webhook_events HTTP 422Escolha ao menos um evento público para o webhook, com o nome do contrato.
invalid_webhook_url HTTP 422O webhook é uma URL HTTPS pública, sem usuário e senha, de até 500 caracteres. Endereço da rede interna não é aceito.
items_required HTTP 422A ordem precisa de pelo menos uma parada.
lot_not_found HTTP 422O lote não existe para este produto. O lote nasce no recebimento da nota.
lot_required HTTP 422O produto é rastreado por lote: diga de qual lote é o item.
missing_description HTTP 422O nome do produto (description) é obrigatório.
missing_identity HTTP 422Informe pelo menos um identificador: sku ou ean.
no_aisle HTTP 422O padrão de endereço deste CD não tem corredor: reconte posição por posição.
order_line_unknown_product HTTP 422Há linha com produto fora do catálogo (nem pelo EAN, nem pelo SKU). Cadastre o produto antes de importar.
reason_required HTTP 422Esta ação pede o motivo (reason).
unknown_product HTTP 422Há item na nota fora do catálogo. Cadastre o item e importe a nota de novo; a nota inteira volta.
unknown_trait HTTP 422O campo não existe para itens desta empresa.
unknown_uom HTTP 422A unidade de medida não existe nesta empresa.

HTTP 429 · Muitos pedidos

rate_limited HTTP 429Muitos pedidos por segundo com esta chave. Espere o Retry-After, em segundos, e tente de novo.

HTTP 503 ·

vault_unavailable HTTP 503O cofre do servidor está fechado agora e nada foi guardado. Tente de novo em alguns minutos.