Visão Geral
Quando uma requisição à API v2 falha, o retorno inclui campos específicos para identificar o problema:
retorno.status: “Erro”retorno.codigo_erro: Código numérico do erroretorno.erros[]: Lista de mensagens descritivas dos erros
Códigos de Erro Comuns
| Código | Descrição |
|---|
| 1 | Token inválido ou expirado |
| 2 | Token não informado |
| 20 | Consulta não retornou registros |
| 31 | Erro de validação nos dados enviados |
| 32 | Registro não localizado |
Estrutura de Retorno de Erro
{
"retorno": {
"status_processamento": 1,
"status": "Erro",
"codigo_erro": 2,
"erros": [
{
"erro": "token invalido"
}
]
}
}
Erros de Validação
Para operações de inclusão e alteração, erros específicos são retornados dentro de retorno.registros[].registro.erros[]:
{
"retorno": {
"status_processamento": 2,
"status": "Erro",
"registros": [
{
"registro": {
"sequencia": "1",
"status": "Erro",
"codigo_erro": 31,
"erros": [
{
"erro": "O número de sequência deve ser informado"
},
{
"erro": "O nome do contato deve ser informado"
}
]
}
}
]
}
}
Status de Processamento
O campo status_processamento indica o resultado da operação:
| Valor | Significado |
|---|
| 1 | Erro de autenticação |
| 2 | Erro de validação ou dados não encontrados |
| 3 | Processamento bem-sucedido |
A documentação completa de todos os códigos de erro não está disponível publicamente. As mensagens em retorno.erros[] fornecem detalhes específicos sobre cada erro encontrado.
Tratamento de Erros
Boas Práticas
- Sempre verifique o campo
status antes de processar o retorno
- Leia as mensagens em
erros[] para entender o problema específico
- Use o
codigo_erro para tratamento programático
- Implemente retry logic para erros temporários (ex: timeout)
- Valide os dados localmente antes de enviar para reduzir erros de validação
Exemplo de Tratamento em PHP
$resposta = json_decode($response, true);
if ($resposta['retorno']['status'] === 'Erro') {
$codigo = $resposta['retorno']['codigo_erro'];
$mensagens = array_column($resposta['retorno']['erros'], 'erro');
if ($codigo == 1 || $codigo == 2) {
// Erro de autenticação
error_log('Token inválido ou não informado');
} elseif ($codigo == 20) {
// Nenhum registro encontrado
return [];
} elseif ($codigo == 31 || $codigo == 32) {
// Erro de validação ou registro não encontrado
error_log('Erros: ' . implode(', ', $mensagens));
}
return false;
}
// Processar resposta de sucesso
return $resposta['retorno'];
Consulte Também
