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

# Erros e respostas

> Entenda o formato padrão das respostas da API

Todas as respostas da API Safefy seguem um formato consistente, facilitando o tratamento de sucesso e erro.

## Formato de sucesso

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Pending",
    "amount": 1000
  },
  "message": "Transação criada com sucesso"
}
```

## Formato de erro

```json theme={null}
{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo 'amount' deve ser maior que zero"
  }
}
```

***

## Códigos HTTP

| Código | Significado                         |
| ------ | ----------------------------------- |
| `200`  | Sucesso                             |
| `201`  | Recurso criado                      |
| `400`  | Erro de validação                   |
| `401`  | Não autenticado                     |
| `403`  | Não autorizado                      |
| `404`  | Recurso não encontrado              |
| `409`  | Conflito (ex: externalId duplicado) |
| `429`  | Rate limit excedido                 |
| `500`  | Erro interno do servidor            |

***

## Códigos de erro

| Código                    | Descrição                          |
| ------------------------- | ---------------------------------- |
| `VALIDATION_ERROR`        | Campos inválidos ou ausentes       |
| `AUTHENTICATION_REQUIRED` | Token não fornecido                |
| `INVALID_TOKEN`           | Token inválido ou expirado         |
| `FORBIDDEN`               | IP não autorizado ou sem permissão |
| `NOT_FOUND`               | Recurso não encontrado             |
| `DUPLICATE_EXTERNAL_ID`   | externalId já existe               |
| `INSUFFICIENT_BALANCE`    | Saldo insuficiente para saque      |
| `RATE_LIMIT_EXCEEDED`     | Muitas requisições                 |
| `INTERNAL_ERROR`          | Erro interno                       |

***

## Tratando erros

```javascript theme={null}
try {
  const response = await fetch('https://api-payment.safefypay.com.br/v1/transactions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });
  
  const result = await response.json();
  
  if (result.error) {
    // Trata o erro baseado no codigo
    switch (result.error.code) {
      case 'VALIDATION_ERROR':
        console.error('Dados inválidos:', result.error.message);
        break;
      case 'INVALID_TOKEN':
        // Renova o token e tenta novamente
        break;
      default:
        console.error('Erro:', result.error.message);
    }
  } else {
    // Sucesso
    console.log('Transação criada:', result.data);
  }
} catch (error) {
  console.error('Erro de rede:', error);
}
```

***

## Rate limiting

Quando você excede o limite de requisições, a API retorna `429` com o header `Retry-After`:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisições excedido. Tente novamente em 60 segundos."
  }
}
```

<Tip>
  Use o header Retry-After para saber quando pode tentar novamente.
</Tip>