Referência de erros

Nesta página, você encontrará uma apresentação dos tipos de erros que a API do Koncili pode retornar.

---

Observações importantes:

• Esta tabela lista todos os erros conhecidos que podem ocorrer durante a integração com a API Koncili
• Cada erro inclui um código HTTP, um código interno, formatado {httpCode}-{internalCode} (exemplo: 404-1) e mensagem padrão e endpoints onde pode ocorrer
• Para erros não listados, consulte o padrão RFC 7807
• Em caso de dúvidas, entre em contato com nosso suporte: suporte@koncili.com.br

Tabela de referência

Código	Status HTTP	Endpoints	Descrição	Solução
400-0	400	Todos endpoints	Valores inválidos no payload
400-2	400	Todos endpoints	Canal não suporta importação via API
400-3	400	POST /order		Datas conflitantes
403-1	403	Todos endpoints	A conta está inativa
403-2	403	Todos endpoints	A conta não está autorizada a operar o canal
404-1	404	Todos endpoints	A conta informada não existe
404-2	404	Todos endpoints	O canal informado não existe
404-3	404	GET /order DELETE /order	O pedido indicado não existe
403	403	Todos endpoints	{"response": "NO_TOKEN"} Token ausente ou expirado	Gere um novo token via /public/api/auth/token
403	403	Todos endpoints	IP não autorizado	Libere o IP via /externalapi/ip-segmentation
502	502	Todos endpoints	Falha de comunicação	Verifique o corpo da requisição e reenvie após alguns segundos
404	404	Todos endpoints	Endpoint incorreto	Confirme o endpoint no ambiente correto (sandbox ou produção)
500	500	Todos endpoints	Erro interno da API	Envie os detalhes (endpoint, hora, corpo da requisição) para integracaoapi@koncili.com

Como interpretar os erros

Código de Erro: Combinação do status HTTP + código único interno (ex: 404-3)

1. Erros 4xx: Problemas com a requisição
2. Erros 5xx: Problemas no servidor (geralmente temporários)

Formato de resposta

As respostas da API são formatadas por padrão da seguinte forma:

{
  "errorMessage": "Channel invalid_channel not found",
  "errorCode": "404-2",
  "errorSource": "KIE"
}

Para payload mal formatado, neste exemplo, um pedido é enviado com um status não aceito pela API:

{
  "errorMessage": "Bad Request",
  "errorDetails": [
    {
      "message": "JSON decoding error: Invalid ChannelStatusType value. Accepted values are: INVOICED, PAID_WAITING_DELIVERY, CONCLUDED, CANCELED"
    }
  ],
  "errorCode": "400-0",
  "errorSource": "KIE"
}

O campo errorSource pode assumir dois valores:

1. KIE (Koncili internal error), erros relacionados à lógica de negócio
   • Cenários típicos:
     • Validação de payload
     • Conflito de dados
     • Regras de negócio violadas
2. TPE (Third Party Error), falhas em integrações externas: - Cenários típicos: - APIs de marketplaces indisponíveis - Timeout em serviços parceiros - Formato inesperado em respostas externas

Fluxo recomendado para tratamento

Nota

Erros do tipo TPE geralmente se resolvem automaticamente em tentativas subsequentes. Caso persistam por mais de 15 minutos, contate nosso time técnico.