> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enrow.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Tratamento de Erros
> Trate os erros da API Enrow com elegância — formatos de resposta, códigos de status, lógica de retentativa e boas práticas
A API Enrow sinaliza problemas com códigos de status HTTP e um corpo de erro em JSON. Este guia explica os formatos de resposta de erro, os erros mais comuns e como corrigi-los, e como construir uma lógica de retentativa confiável. Para a lista completa de códigos, consulte [Códigos de status](/pt/status-codes).
## Como é uma resposta de erro?
A maioria dos erros da API Enrow retorna um objeto JSON simples com um único campo `message`:
```json theme={null}
{
"message": "Human-readable error description"
}
```
A única exceção é um erro de **crédito insuficiente (402)** em endpoints **individuais** (buscar e-mail/telefone individual, verificar individual), que retorna um campo `reason` junto com `success`:
```json theme={null}
{
"reason": "Insufficient credits",
"success": false
}
```
As respostas de erro nunca incluem os campos `error`, `status` ou `retry_after`. Leia o código de status HTTP para ramificar sua lógica e leia `message` (ou `reason`) para a descrição legível.
## Quais são os erros mais comuns e como corrigi-los?
Os erros abaixo cobrem a grande maioria das requisições com falha. Cada um vem com o corpo da resposta que a API retorna e a correção.
### Por que estou recebendo um 400 Bad Request?
Um `400` significa que o payload da requisição está malformado ou que falta um parâmetro obrigatório:
```json theme={null}
{
"message": "both company_domain and company_name are absent, input payload needs at least one of them"
}
```
**Correção**: Verifique se você está fornecendo todos os parâmetros obrigatórios para o endpoint. Por exemplo, [Buscar E-mail](/pt/api-reference/email-finder/find-single) exige `fullname` mais `company_domain` ou `company_name`.
### Por que estou recebendo um 401 Unauthorized?
Um `401` significa que a chave de API está ausente ou inválida:
```json theme={null}
{
"message": "This apikey is not valid"
}
```
**Correção**: Verifique se a chave de API está correta e é enviada no cabeçalho `x-api-key` (não em `Authorization`). Consulte [Autenticação](/pt/authentication) para saber como passar a chave em cada requisição.
### Por que estou recebendo um 402 Insufficient Credits?
Um `402` significa que a conta não tem créditos suficientes para executar a requisição:
```json theme={null}
{
"reason": "Insufficient credits",
"success": false
}
```
Em endpoints **em lote**, o mesmo `402` é retornado com o formato padrão `{ "message": "..." }`.
**Correção**: Verifique o saldo de créditos no [Dashboard](https://app.enrow.io) ou via `GET /account/info`. Adicione créditos ou faça upgrade do plano em [enrow.io/pricing](https://enrow.io/pricing). Consulte [Créditos e cobrança](/pt/credits-billing) para saber como os créditos são consumidos por endpoint.
### Por que estou recebendo um 429 Rate Limit Exceeded?
Um `429` significa que muitas requisições foram enviadas em um curto intervalo:
```json theme={null}
{
"message": "Too Many Requests"
}
```
**Correção**: Aguarde e tente novamente com backoff exponencial. Consulte [Limites de taxa](/pt/rate-limits) para os limites por plano.
### Por que estou recebendo um 500 Internal Server Error?
Um `500` significa que algo falhou no lado da Enrow:
```json theme={null}
{
"message": "An unexpected error occurred"
}
```
**Correção**: Tente novamente com backoff. Se o problema persistir, entre em contato com [api@enrow.io](mailto:api@enrow.io).
## Como trato erros no código?
Verifique o status HTTP antes de analisar o corpo de sucesso e, em seguida, gere um erro que carregue o código de status para que sua lógica de retentativa possa ramificar com base nele. O campo `message` contém a descrição da maioria dos erros, e `reason` a contém para as respostas `402` de endpoints individuais.
```javascript Node.js theme={null}
async function findEmail(contact) {
const response = await fetch('https://api.enrow.io/email/find/single', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.ENROW_API_KEY
},
body: JSON.stringify(contact)
});
if (!response.ok) {
const body = await response.json();
const error = new Error(`Enrow API error ${response.status}: ${body.message || body.reason}`);
error.status = response.status;
throw error;
}
return await response.json();
}
```
```python Python theme={null}
import requests
import os
def find_email(contact):
response = requests.post(
"https://api.enrow.io/email/find/single",
json=contact,
headers={
"Content-Type": "application/json",
"x-api-key": os.getenv("ENROW_API_KEY")
}
)
if not response.ok:
error = response.json()
message = error.get("message") or error.get("reason")
raise Exception(f"Enrow API error {response.status_code}: {message}")
return response.json()
```
## Como tento novamente requisições com falha?
Tente novamente apenas os erros que valem a pena repetir — `429` e `5xx` — e aplique backoff exponencial entre as tentativas. Erros de cliente na faixa `4xx` (exceto `429`) indicam um problema com a própria requisição, portanto repeti-los não ajudará.
```javascript theme={null}
async function requestWithRetry(fn, maxRetries = 3, baseDelay = 1000) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await fn();
} catch (error) {
const isLastAttempt = attempt === maxRetries - 1;
// Don't retry client errors (except rate limits)
if (error.status >= 400 && error.status < 500 && error.status !== 429) {
throw error;
}
if (isLastAttempt) throw error;
const delay = baseDelay * Math.pow(2, attempt);
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}
```
## Boas práticas
* **Não tente novamente erros 4xx** (exceto 429) — corrija a requisição
* **Tente novamente erros 429** — aplique backoff com atrasos exponenciais antes de repetir
* **Tente novamente erros 5xx** — com backoff exponencial
* **Use webhooks** em vez de polling para evitar atingir os limites de taxa desnecessariamente — consulte [Como os webhooks funcionam](/pt/how-webhooks-work)
* **Registre os erros com contexto** — inclua o endpoint, os parâmetros e o timestamp para depuração
## FAQ
Em endpoints individuais (buscar e-mail/telefone individual, verificar individual), um `402` retorna `{ "reason": "Insufficient credits", "success": false }`. Em endpoints em lote, o mesmo `402` retorna o formato padrão `{ "message": "..." }`. Ler tanto `message` quanto `reason` (como fazem os exemplos de código) cobre os dois casos.
Tente novamente erros `429` (limite de taxa) e `5xx` (servidor) com backoff exponencial. Não tente novamente outros erros `4xx` como `400`, `401` ou `402` — eles indicam um problema com a requisição, a chave de API ou o saldo de créditos que repetir sozinho não resolverá.
Não. As respostas de erro nunca incluem os campos `retry_after`, `error` ou `status`. Use seu próprio backoff exponencial entre as retentativas. Consulte [Limites de taxa](/pt/rate-limits) para os limites que se aplicam ao seu plano.
Para a maioria dos erros, a descrição está no campo `message`. Para um `402` de crédito insuficiente em um endpoint individual, ela está no campo `reason`. Sempre ramifique sua lógica com base no código de status HTTP em vez de analisar o texto da mensagem.
## Próximos passos
A lista completa de códigos de status HTTP e seus significados.
Entenda os limites de requisição por plano para evitar erros 429.
Como passar sua chave de API no cabeçalho x-api-key.
Veja como os créditos são consumidos para cada endpoint.