# 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.

**Uma recusa**

```json
{
  "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`](/erros/invalid_active.md) (HTTP 400): Filtro de situação inválido: use `true` ou `false`.
- [`invalid_block_reason`](/erros/invalid_block_reason.md) (HTTP 400): Recorte de bloqueio inválido: use `any` ou uma das razões declaradas no parâmetro.
- [`invalid_idempotency_key`](/erros/invalid_idempotency_key.md) (HTTP 400): Toda escrita pede o cabeçalho `Idempotency-Key` com um UUID.
- [`invalid_limit`](/erros/invalid_limit.md) (HTTP 400): `limit` fora da faixa: de 1 a 200.
- [`invalid_offset`](/erros/invalid_offset.md) (HTTP 400): `offset` inválido: um inteiro de zero para cima.
- [`invalid_order`](/erros/invalid_order.md) (HTTP 400): Ordenação inválida: use um dos valores declarados no parâmetro.
- [`invalid_policy`](/erros/invalid_policy.md) (HTTP 400): Recorte de política inválido: use um dos valores declarados no parâmetro.
- [`invalid_status`](/erros/invalid_status.md) (HTTP 400): Situação inválida para este filtro ou campo: use um dos valores declarados.
- [`invalid_view`](/erros/invalid_view.md) (HTTP 400): Recorte inválido: use um dos valores declarados no parâmetro.
- [`version_unknown`](/erros/version_unknown.md) (HTTP 400): A `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`](/erros/api_key_expired.md) (HTTP 401): A chave venceu. Gire a chave no painel e use a nova.
- [`api_key_wrong_environment`](/erros/api_key_wrong_environment.md) (HTTP 401): A chave é do outro ambiente: `ksk_test_` vai em https://stag.kernos.com.br, `ksk_live_` em https://api.kernos.com.br.
- [`unauthenticated`](/erros/unauthenticated.md) (HTTP 401): Credencial ausente, inválida ou expirada.

## HTTP 403 · Sem permissão

- [`agent_token_out_of_scope`](/erros/agent_token_out_of_scope.md) (HTTP 403): O 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`](/erros/api_key_action_not_granted.md) (HTTP 403): A chave não tem esta ação. Edite as ações da chave no painel.
- [`api_key_out_of_scope`](/erros/api_key_out_of_scope.md) (HTTP 403): A chave só vale nas rotas do contrato público.
- [`depot_out_of_reach`](/erros/depot_out_of_reach.md) (HTTP 403): Quem chama não alcança o CD deste objeto. Peça alcance ao CD ou use outra credencial.
- [`forbidden_role`](/erros/forbidden_role.md) (HTTP 403): O papel de quem chama nesta empresa não permite esta ação.
- [`module_not_subscribed`](/erros/module_not_subscribed.md) (HTTP 403): A empresa não assina o módulo desta rota.
- [`tenant_mismatch`](/erros/tenant_mismatch.md) (HTTP 403): A credencial não pertence à empresa do endereço chamado.
- [`tenant_unavailable`](/erros/tenant_unavailable.md) (HTTP 403): A empresa está indisponível no momento.

## HTTP 404 · Não encontrado

- [`depot_not_found`](/erros/depot_not_found.md) (HTTP 404): Não existe CD com esse `depot_code` nesta empresa.
- [`dock_not_found`](/erros/dock_not_found.md) (HTTP 404): A doca informada não existe neste CD.
- [`not_found`](/erros/not_found.md) (HTTP 404): Não existe objeto com esse identificador nesta empresa.

## HTTP 409 · Conflito

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

## HTTP 422 · Não processável

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

## HTTP 429 · Muitos pedidos

- [`rate_limited`](/erros/rate_limited.md) (HTTP 429): Muitos pedidos por segundo com esta chave. Espere o `Retry-After`, em segundos, e tente de novo.

## HTTP 503 ·

- [`vault_unavailable`](/erros/vault_unavailable.md) (HTTP 503): O cofre do servidor está fechado agora e nada foi guardado. Tente de novo em alguns minutos.