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

# Tratamento de Erros

> Melhores práticas para lidar com erros da API

## Formato de Resposta de Erro

A KillB retorna respostas de erro padronizadas:

```json theme={null}
{
  "errorCode": "USER.0001",
  "message": ["Usuário não encontrado"],
  "statusCode": "404",
  "arguments": [
    {
      "key": "userId",
      "value": "invalid-id"
    }
  ]
}
```

## Códigos de Status HTTP

| Status | Significado         | Ação                              |
| ------ | ------------------- | --------------------------------- |
| `200`  | Sucesso             | Processar resposta                |
| `201`  | Criado              | Recurso criado com sucesso        |
| `400`  | Requisição Inválida | Corrigir parâmetros da requisição |
| `401`  | Não Autorizado      | Atualizar token                   |
| `403`  | Proibido            | Verificar permissões              |
| `404`  | Não Encontrado      | Recurso não existe                |
| `409`  | Conflito            | Recurso já existe                 |
| `429`  | Muitas Requisições  | Implementar backoff               |
| `500`  | Erro do Servidor    | Tentar novamente com backoff      |

## Códigos de Erro Comuns

### Erros de Autenticação

| Código      | Mensagem              | Solução                   |
| ----------- | --------------------- | ------------------------- |
| `AUTH.0001` | Credenciais inválidas | Verificar email/senha     |
| `AUTH.0002` | Token expirado        | Atualizar token de acesso |
| `AUTH.0003` | Token inválido        | Re-autenticar             |

### Erros de Usuário

| Código      | Mensagem               | Solução                        |
| ----------- | ---------------------- | ------------------------------ |
| `USER.0001` | Usuário não encontrado | Verificar ID do usuário        |
| `USER.0002` | Documento inválido     | Verificar formato do documento |
| `USER.0003` | Email já existe        | Usar email diferente           |
| `USER.0004` | Usuário menor de idade | Usuário deve ter 18+           |

### Erros de Ramp

| Código      | Mensagem                   | Solução                        |
| ----------- | -------------------------- | ------------------------------ |
| `RAMP.0001` | Cotação expirada           | Criar nova cotação             |
| `RAMP.0002` | Saldo insuficiente         | Verificar saldo pré-financiado |
| `RAMP.0003` | Limite do usuário excedido | Atualizar nível KYC            |
| `RAMP.0004` | Conta inválida             | Verificar status da conta      |

## Estratégia de Tratamento de Erros

```javascript theme={null}
class KillBAPIError extends Error {
  constructor(response) {
    super(response.message.join(', '));
    this.errorCode = response.errorCode;
    this.statusCode = response.statusCode;
    this.arguments = response.arguments;
  }
}

const makeAPIRequest = async (endpoint, options) => {
  try {
    const response = await fetch(endpoint, options);
    
    if (!response.ok) {
      const error = await response.json();
      throw new KillBAPIError(error);
    }
    
    return await response.json();
    
  } catch (error) {
    if (error instanceof KillBAPIError) {
      // Lidar com erros da API
      console.error(`Erro da API ${error.errorCode}:`, error.message);
      
      if (error.statusCode === '401') {
        // Token expirado, atualizar
        await refreshToken();
        return makeAPIRequest(endpoint, options);
      }
      
      if (error.errorCode === 'RAMP.0001') {
        // Cotação expirada, obter nova
        const newQuote = await getNewQuotation();
        // Tentar novamente com nova cotação
      }
    }
    
    throw error;
  }
};
```

## Lógica de Retry

Implemente backoff exponencial:

```javascript theme={null}
const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // Não tente novamente erros de cliente (4xx)
      if (error.statusCode && error.statusCode < 500) {
        throw error;
      }
      
      // Backoff exponencial
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};

// Uso
const user = await retryWithBackoff(() => createUser(userData));
```

## Mensagens Amigáveis ao Usuário

Mapeie erros técnicos para mensagens de usuário:

```javascript theme={null}
const getUserMessage = (error) => {
  const messages = {
    'AUTH.0002': 'Sua sessão expirou. Por favor, faça login novamente.',
    'USER.0003': 'Este email já está registrado.',
    'RAMP.0001': 'A cotação de preço expirou. Por favor, tente novamente.',
    'RAMP.0003': 'O valor da transação excede seu limite. Por favor, verifique sua identidade para aumentar limites.'
  };
  
  return messages[error.errorCode] || 'Ocorreu um erro. Por favor, tente novamente.';
};
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Limites de Taxa" icon="gauge" href="/pt/resources/rate-limits">
    Entendendo limites de taxa da API
  </Card>

  <Card title="Melhores Práticas" icon="star" href="/pt/resources/best-practices">
    Dicas de integração de produção
  </Card>
</CardGroup>