Diagnóstico
Erros
Códigos HTTP, mensagens comuns e erros retornados quando a API rejeita uma solicitação antes de criar ou consultar uma operação.
Formato dos erros
Quando a API rejeita uma solicitação, o corpo retorna erro.codigo, erro.mensagem e, quando útil, erro.campo e erro.acao com o que precisa ser corrigido.
Exemplo de erroJSON
1{2 "erro": {3 "codigo": "API_KEY_INVALIDA",4 "mensagem": "API key invalida ou inativa.",5 "acao": "Confira se a chave foi copiada do portal do parceiro e se está ativa."6 }7}HTTP Status
| Campo | Tipo | Descrição |
|---|---|---|
| 400 | HTTP | Revise JSON, campos obrigatórios, formatos e regras como comanda obrigatória em fila manual. |
| 401 | HTTP | Envie x-api-key ativa. GET /v1/health ajuda a diagnosticar a credencial. |
| 403 | HTTP | A API key não tem permissão para o documentoCliente informado. |
| 404 | HTTP | Smart POS não encontrado para o cliente informado ou nenhum Smart POS disponível no modo manual. |
| 409 | HTTP | O campo referencia já foi usado. Reutilize o retorno salvo ou gere uma nova referência para uma nova tentativa. |
| 500 | HTTP | Erro interno inesperado. Preserve a referência e o payload para tentar novamente com segurança depois. |
Erros comuns
| Campo | Tipo | Descrição |
|---|---|---|
| API_KEY_NAO_INFORMADA | 401 | Envie a chave da integração no header x-api-key. |
| API_KEY_INVALIDA | 401 | Confira se x-api-key foi enviado sem espaços extras e se a chave está ativa no portal do parceiro. |
| JSON_INVALIDO | 400 | Envie um objeto JSON válido no corpo da requisição. |
| CAMPO_OBRIGATORIO | 400 | Preencha o campo obrigatório indicado em erro.campo antes de reenviar. |
| CAMPO_INVALIDO | 400 | Revise formato, tamanho ou tipo do campo indicado em erro.campo. |
| VALOR_INVALIDO | 400 | Revise valores numéricos como valorCentavos e parcelas. |
| FORMA_PAGAMENTO_INVALIDA | 400 | Revise formaPagamento, parcelas e parcelamento antes de reenviar. |
| DOCUMENTO_CLIENTE_INVALIDO | 400 | Envie documentoCliente com CPF ou CNPJ numérico do cliente vinculado aos Smart POS. |
| SMARTPOS_NAO_ENCONTRADO | 404 | Confirme se smartposId pertence ao documentoCliente informado. Em pagamento manual, você pode omitir smartposId para publicar nos Smart POS disponíveis. |
| SMARTPOS_INDISPONIVEL | 404 | Nenhum Smart POS disponível foi encontrado para publicar uma operação manual sem smartposId. |
| WEBHOOK_NAO_CONFIGURADO | 400 | Cadastre a URL do webhook no portal do parceiro antes de operar. |
| COMANDA_OBRIGATORIA_MODO_MANUAL | 400 | Quando modoExecucao for manual, envie comanda.identificacao e os dados que devem aparecer no card do operador. |
| REFERENCIA_DUPLICADA | 409 | A referência já foi usada em uma tentativa operacional anterior. |
Eventos finais não são erro HTTP
Recusa no Smart POS, cancelamento pelo operador, falha operacional, timeout de comunicação e falha de impressão são resultados da operação. Trate esses casos pela aba Webhook da rota correspondente, não como erro HTTP.