> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.erp.olist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de Erro

> Códigos de erro retornados pela API v2

## 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 erro
* `retorno.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

```json theme={null}
{
  "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[]`:

```json theme={null}
{
  "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                 |

<Info>
  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.
</Info>

## Tratamento de Erros

### Boas Práticas

1. **Sempre verifique o campo `status`** antes de processar o retorno
2. **Leia as mensagens em `erros[]`** para entender o problema específico
3. **Use o `codigo_erro`** para tratamento programático
4. **Implemente retry logic** para erros temporários (ex: timeout)
5. **Valide os dados localmente** antes de enviar para reduzir erros de validação

### Exemplo de Tratamento em PHP

```php theme={null}
$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

* [Limites da API](/api-v2/limites) - Entenda os rate limits e quotas
* [Fluxo Sugerido](/api-v2/fluxo-sugerido) - Melhores práticas de integração
* [Introdução](/api-v2/introducao) - Informações básicas da API v2