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

# Erros

> Os códigos que cada parte da API devolve, o que causou cada um e o que fazer.

As duas partes da API erram de formas diferentes e devolvem corpos diferentes, porque
foram escritas em momentos diferentes. Esta página cobre as duas.

## Consulta de CPF e CNPJ

O corpo do erro é sempre o mesmo objeto, e o que você deve tratar é o `codigo`. Ele é uma
string estável nossa, não o número que o bureau devolveu, justamente para o seu `if`
continuar valendo se o fornecedor mudar.

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "erro": {
    "codigo": "nao_encontrado",
    "mensagem": "Documento não localizado."
  }
}
```

| Código                  | HTTP | Causa                                               | O que fazer                                |
| ----------------------- | ---- | --------------------------------------------------- | ------------------------------------------ |
| `sem_chave`             | 401  | Nenhuma credencial no cabeçalho                     | Envie `Authorization: Bearer`              |
| `chave_invalida`        | 401  | A chave não existe                                  | Confira o valor copiado                    |
| `chave_revogada`        | 401  | A chave foi revogada no app                         | Gere outra                                 |
| `chave_expirada`        | 401  | Passou da data de expiração                         | Gere outra                                 |
| `chave_desativada`      | 403  | Desligada sem ser revogada                          | Ligue-a na tela de chaves                  |
| `sem_escopo`            | 403  | A chave não cobre esse tipo de documento            | Edite os escopos da chave                  |
| `organizacao_bloqueada` | 403  | A conta está bloqueada                              | Fale com o suporte                         |
| `recurso_indisponivel`  | 404  | A instância não tem a consulta habilitada           | Fale com quem cuida da implantação         |
| `documento_invalido`    | 400  | Dígito verificador, formato ou sintaxe              | Corrija antes de reenviar                  |
| `produto_desconhecido`  | 400  | O id não está no catálogo                           | Confira em `/api/v1/produtos`              |
| `requisicao_invalida`   | 400  | Corpo malformado ou campo faltando                  | Confira o JSON                             |
| `limite_por_minuto`     | 429  | Requisições demais no minuto                        | Aguarde o `Retry-After`                    |
| `teto_diario`           | 429  | Teto do dia atingido                                | Aguarde a virada, ou aumente o teto        |
| `teto_mensal`           | 429  | Teto do mês atingido                                | Aumente o teto na tela de chaves           |
| `nao_encontrado`        | 404  | O bureau não tem o documento                        | Nada a fazer, o documento não está na base |
| `consulta_indisponivel` | 402  | O produto está fora do contrato, ou o saldo acabou  | Fale com o suporte                         |
| `bureau_indisponivel`   | 502  | Fornecedor fora do ar, timeout, credencial recusada | Tente de novo com espera crescente         |

Os erros de `400` e `403` não custam nada: eles acontecem antes de qualquer chamada paga.
O `nao_encontrado` e o `consulta_indisponivel` podem ter custado, porque quem respondeu
foi o bureau.

## Entrada de contatos

Aqui o corpo traz um campo `error` com texto em inglês, porque é lido por máquina.

| Código | Corpo                                          | Causa                                               | O que fazer                                         |
| ------ | ---------------------------------------------- | --------------------------------------------------- | --------------------------------------------------- |
| `400`  | `Valid email is required`                      | O corpo não trouxe email, ou o valor não contém `@` | Torne o email obrigatório no seu formulário         |
| `400`  | `Organization has not completed onboarding...` | A organização não tem etapas de funil configuradas  | Configure o funil na tela de Pipeline               |
| `400`  | `No active members found in organization`      | Não há membro ativo para receber o contato          | Reative alguém em Configurações, Equipe             |
| `403`  | `Webhook is disabled`                          | O webhook existe mas está desligado                 | Ligue-o na tela de webhooks                         |
| `404`  | `Invalid webhook token`                        | O token não corresponde a nenhum webhook            | Confira a URL; o token pode ter sido regerado       |
| `500`  | `Internal error`                               | Falha do lado da plataforma                         | Tente de novo; se persistir, escreva para o suporte |

## Como tratar do seu lado

<AccordionGroup>
  <Accordion title="400 é definitivo, não tente de novo">
    Problema de dado ou de configuração. Repetir a mesma requisição devolve o mesmo erro.
    Registre e siga.
  </Accordion>

  <Accordion title="401 e 403 pedem intervenção humana">
    Credencial trocada, chave sem escopo, webhook desligado. Alerte quem cuida da
    integração em vez de tentar de novo em laço.
  </Accordion>

  <Accordion title="429 diz quando voltar">
    Respeite o `Retry-After` quando ele vier. Quando não vier, o caso é teto mensal, e
    esperar não resolve: alguém precisa aumentar o teto.
  </Accordion>

  <Accordion title="500 e 502 valem tentativa">
    Falha temporária. Uma ou duas tentativas com espera crescente resolvem a maioria dos
    casos. Não repita indefinidamente.
  </Accordion>
</AccordionGroup>

## Sucesso duplicado

A entrada de contatos **não** é idempotente: duas requisições iguais criam dois contatos.
A consulta é diferente, porque o cache de 30 dias faz a segunda chamada do mesmo documento
voltar sem custo, com `cache: true`.