# Tratamento de Erros

A Easypay utiliza códigos de estado de resposta HTTP padrão para indicar o sucesso ou falha das solicitações à API.

## Códigos de Estado HTTP

A API utiliza três intervalos principais de códigos de estado:

- **2xx Sucesso**: A sua solicitação foi bem-sucedida
- **4xx Erro do Cliente**: Houve um erro com as informações fornecidas
- **5xx Erro do Servidor**: Ocorreu um erro nos servidores da Easypay (raro)


## Códigos de Estado Comuns

| Código de Estado | Significado | O Que Fazer |
|  --- | --- | --- |
| `200 OK` | Solicitação bem-sucedida | Processar a resposta |
| `201 Created` | Recurso criado com sucesso | Processar o recurso recém-criado |
| `204 No Content` | Solicitação bem-sucedida, sem conteúdo para retornar | Continuar normalmente |
| `400 Bad Request` | Parâmetros de solicitação inválidos | Verificar o payload da solicitação |
| `403 Forbidden` | Autenticação falhou | Verificar as suas credenciais |
| `404 Not Found` | Recurso não existe | Verificar o ID do recurso |
| `409 Conflict` | Solicitação conflitua com estado atual | Rever os detalhes do conflito |
| `429 Too Many Requests` | Limite de taxa excedido | Diminuir as suas solicitações |
| `500 Internal Server Error` | Erro do servidor | Tentar novamente ou contactar suporte |
| `502 Bad Gateway` | Problema temporário do servidor | Tentar novamente a solicitação |
| `503 Service Unavailable` | Serviço temporariamente indisponível | Tentar novamente a solicitação |


## Formato de Resposta de Erro

Quando ocorre um erro, a API retorna uma resposta JSON com detalhes do erro:


```json
{
  "status": "error",
  "message": "Descrição do erro",
  "code": "CÓDIGO_ERRO",
  "doc_url": "https://docs.easypay.pt/errors/CÓDIGO_ERRO"
}
```

## Tipos de Erro

### Erro de Autenticação (403)

**Causas Possíveis**:

- Cabeçalhos `AccountId` ou `ApiKey` em falta ou inválidos
- Conta foi bloqueada
- Permissões insuficientes para a ação solicitada


**Exemplo**:


```json
{
  "status": "error",
  "message": "Authentication Error: Invalid AccountId or ApiKey",
  "code": "AUTHENTICATION_ERROR"
}
```

**Resolução**: Verifique as suas credenciais e assegure que a sua conta está ativa.

### Erro de Tipo de Conteúdo Inválido (415)

**Causa**: Forneceu um cabeçalho `Content-Type` inválido ou não suportado.

**Exemplo**:


```json
{
  "status": "error",
  "message": "Invalid Content Type Error: Unsupported content type",
  "code": "INVALID_CONTENT_TYPE"
}
```

**Resolução**: Defina o cabeçalho `Content-Type` como `application/json`.

### Erro de JSON Inválido (400)

**Causa**: O corpo da solicitação contém JSON malformado.

**Exemplo**:


```json
{
  "status": "error",
  "message": "Invalid JSON Error: Unexpected token",
  "code": "INVALID_JSON"
}
```

**Resolução**: Valide o seu payload JSON antes de enviar a solicitação.

### Erro de Parâmetros Inválidos (400)

**Causa**: Parâmetros obrigatórios estão em falta ou são inválidos.

**Exemplo**:


```json
{
  "status": "error",
  "message": "Invalid Params Error: Field 'value' is required",
  "code": "INVALID_PARAMS",
  "doc_url": "https://docs.easypay.pt/errors/INVALID_PARAMS"
}
```

**Resolução**: Reveja a mensagem de erro e assegure que todos os parâmetros obrigatórios são fornecidos com valores válidos.

### Erro Interno (500)

**Causa**: Ocorreu um erro inesperado nos servidores da Easypay.

**Exemplo**:


```json
{
  "status": "error",
  "message": "Internal Error: An unexpected error occurred",
  "code": "INTERNAL_ERROR"
}
```

**Resolução**: Tente novamente a solicitação. Se o problema persistir, contacte o suporte.

## Lógica de Retentativa

Alguns erros são seguros para tentar novamente, enquanto outros não são. A API inclui um cabeçalho `X-Easypay-Should-Retry` para ajudá-lo a decidir:


```
X-Easypay-Should-Retry: true
```

### Quando Tentar Novamente

**Seguro para Tentar Novamente** (quando `X-Easypay-Should-Retry: true` ou para estes códigos de estado):

- `409 Conflict` - Pode indicar que a solicitação original ainda está em trânsito
- `429 Too Many Requests` - Aguardar e tentar novamente
- `502 Bad Gateway` - Problema temporário do servidor
- `503 Service Unavailable` - Serviço temporariamente inativo


**NÃO Tente Novamente**:

- `400 Bad Request` - Corrija primeiro a sua solicitação
- `403 Forbidden` - Corrija primeiro a autenticação
- `404 Not Found` - Recurso não existe
- `422 Unprocessable Entity` - Corrija primeiro os erros de validação


### Estratégia de Retentativa

Se o cabeçalho `X-Easypay-Should-Retry` não estiver presente, use esta estratégia:

1. **Nenhuma resposta recebida**: Tente novamente a solicitação
2. **Código de estado 409, 429, 502 ou 503**: Tente novamente a solicitação
3. **Código de estado 500** em solicitações não-POST: Tente novamente a solicitação
4. **Código de estado 500** em solicitações POST: NÃO tente novamente (pode duplicar recursos)
5. **Todos os outros erros**: NÃO tente novamente


### Exemplo de Implementação de Retentativa


```javascript
async function retryableRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      // Verificar se devemos tentar novamente
      const shouldRetry = response.headers.get('X-Easypay-Should-Retry');
      if (shouldRetry === 'true' || [409, 429, 502, 503].includes(response.status)) {
        if (i < maxRetries - 1) {
          await sleep(Math.pow(2, i) * 1000); // Backoff exponencial
          continue;
        }
      }

      return response;
    } catch (error) {
      if (i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}
```

## Boas Práticas

1. **Verifique Sempre os Códigos de Estado**: Não assuma que as solicitações são bem-sucedidas
2. **Registe Erros**: Mantenha logs detalhados de erros para depuração
3. **Trate Erros Graciosamente**: Forneça feedback significativo aos utilizadores
4. **Use Idempotência**: Use chaves de idempotência para retentativas seguras (ver [Idempotência](/docs/idempotency))
5. **Implemente Backoff Exponencial**: Ao tentar novamente, aumente o tempo de espera entre tentativas
6. **Monitorize Taxas de Erro**: Acompanhe as taxas de erro para identificar problemas precocemente
7. **Respeite Limites de Taxa**: Implemente limitação de taxa para evitar erros 429


## Próximos Passos

- [Idempotência](/docs/idempotency) - Aprenda sobre retentativas seguras com chaves de idempotência
- [Autenticação](/docs/authentication) - Corrija erros de autenticação
- [Início Rápido](/docs/quickstart) - Faça a sua primeira chamada bem-sucedida à API