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

# Tratamento de erros

O tratamento eficaz de erros é crucial para a criação de integrações robustas com a API Localpayment. Compreender os diferentes tipos de erros e seus respectivos códigos ajudará você a diagnosticar problemas rapidamente e a implementar soluções adequadas.

Oferecemos um tratamento de erros abrangente por meio de códigos de status HTTP padronizados e respostas de erro detalhadas. Este guia mostra como você pode lidar com erros de forma eficaz para criar uma integração mais resiliente e fácil de usar.

## Visão geral

O tratamento adequado de erros é crucial para a criação de integrações de pagamento confiáveis. O Localpayment utiliza uma estrutura de erros consistente em todos os endpoints da API para ajudar você a identificar e resolver problemas rapidamente.

> [card] [Códigos padronizados](#http-response-codes)
>
> Códigos de erro consistentes em todos os endpoints da API e métodos de pagamento.

> [card] [Mensagens detalhadas](#error-response-structure)
>
> Descrições em linguagem acessível, com detalhes específicos sobre os erros.

> [card] [Melhores práticas](#best-practices-for-error-handling)
>
> Estratégias comprovadas para lidar com erros em ambientes de produção.

***

## Códigos de resposta HTTP

O Localpayment utiliza códigos de status HTTP padrão para indicar o sucesso ou a falha das solicitações da API:​

| Código HTTP | Status | Descrição |
| - | - | - |
| 200 | `OK` | A solicitação foi bem-sucedida e a resposta contém os dados solicitados. |
| 201 | Criado | O recurso foi criado com sucesso (ex.: novo pagamento iniciado). |
| 400 | Requisição inválida | A solicitação estava malformada, continha parâmetros inválidos ou campos obrigatórios ausentes. |
| 401 | Não autorizado | A autenticação falhou, as credenciais são inválidas ou o token de acesso está ausente/expirado. |
| 403 | Proibido | O pedido foi compreendido, mas recusado devido à insuficiência de autorizações. |
| 404 | Não encontrado | O recurso solicitado não foi encontrado (por exemplo, endpoint ou ID de transação inválido). |
| 409 | Conflito | A solicitação entra em conflito com o estado atual do recurso (por exemplo, transação duplicada). |
| 429 | Muitos pedidos | Limite de requisições excedido. Muitas requisições foram feitas em um determinado período de tempo. |
| 500 | Erro do Servidor Interno | Ocorreu um erro inesperado nos servidores da Localpayment. |

***

## Estrutura de Resposta a Erros

Quando ocorre um erro, o Localpayment retorna um objeto JSON com informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [paymentMethod] + [Is mandatory]"
  },
  "errors": [
    {
      "code": "300",
      "description": "REJECTED",
      "detail": "Invalid param + [paymentMethod] + [Is mandatory]"
    }
  ]
}
```

### Campos de resposta de erro

| Campo | Tipo | Descrição | Exemplo |
| - | - | - | - |
| `status.code` | string | Código de status específico do Localpayment | `300` |
| `status.description` | string | Descrição resumida do erro | `REJECTED` |
| `status.detail` | string | Mensagem de erro detalhada | `Invalid param [paymentMethod]` |
| errors\[] | array | Matriz de objetos de erro específicos | Veja abaixo |
| errors\[].code | string | Código de erro específico da Localpayment | `300` |

***

## Referência de Códigos de Status Internos

Embora a Localpayment use códigos HTTP padrão para o status no nível da requisição, os campos `status.code` e `errors[].code` fornecem o status granular da lógica de negócios e do processamento.

| Intervalo de códigos | Categoria | Significado semântico | Cenários de exemplo |
| - | - | - | - |
| **1xx** | Pendente | A transação foi iniciada, mas aguarda confirmação ou ação final. | `100` (Pendente), `103` (Aprovado, mas não creditado) |
| **2xx** | Sucesso | A transação foi processada e concluída com sucesso. | `200` (Concluído) |
| **3xx** | Validação | A solicitação falhou devido a parâmetros ausentes ou inválidos. | `300` (Parâmetro inválido), `301` (Não autorizado para o país) |
| **7xx** | Lógica de negócios | A transação foi rejeitada devido a regras bancárias ou comerciais. | `701` (Conta inválida), `702` (Fundos insuficientes) |
| **8xx** | Sistema/Fornecedor | A transação foi rejeitada pelo provedor subjacente ou ocorreu um erro interno do sistema. | `801` (Erro de parâmetros), `802` (Rejeitado pelo provedor) |
| **9xx** | Reversão/Negativo | A transação foi estornada, reembolsada ou contestada. | `902` (Reembolsado), `906` (Estorno) |

***

## Cenários de erro comuns

### Erros de autenticação

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid",
  "messages": [
    {
      "token_class": "AccessToken",
      "token_type": "access",
      "message": "Token is invalid or expired"
    }
  ]
}
```

> [!NOTE]
>
> **Solução**
>
> Verifique suas credenciais de API e certifique-se de que seu token de acesso seja válido. Use o endpoint de atualização de token, se necessário.

### Erros de validação

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "46014bdc-c3a7-1b15-8dcf-c7050c1c8199",
  "internalId": "caa4e9aa-f634-497c-ba75-7f88b005ca62",
  "status": {
    "code": "801",
    "description": "REJECTED",
    "detail": "Params error"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [paymentMethod] + doesn't exist for MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.bank.account.[number, type | alias]] + must not be null"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document.type] + is invalid for country MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document] + is invalid for payer type"
    },
    {
      "code": "701",
      "detail": "IncorrectAccountNumber"
    }
  ]
}
```

> [!NOTE]
>
> **Solução**
>
> Revise o array `errors` para identificar problemas específicos de validação de campos. Consulte a documentação da API para obter informações sobre os campos obrigatórios e as especificações de formato.

### Erros de lógica de negócios

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "8c0b537a-e907-4d87-93db-5dab9807e093",
  "internalId": "dddfde6c-b61c-4b0e-8916-d88886133c4d",
  "status": {
    "code": "701",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "701",
      "detail": "Invalid bank account number. Account number verification failed."
    }
  ]
}
```

> [!NOTE]
>
> **Solução**
>
> Esses erros exigem resolução em nível comercial. Verifique os saldos da conta, os limites de transação ou entre em contato com o suporte para obter informações sobre restrições específicas.

***

## Melhores práticas para tratamento de erros

> [!TIP]
>
> **Dica profissional**
>
> Implemente o registro estruturado de logs desde o primeiro dia. Inclua IDs de correlação, códigos de erro e informações de contexto para facilitar a depuração quando ocorrerem problemas em produção.

### Implementar registro abrangente de logs

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
function handleApiError(error, context) {
  const logEntry = {
    timestamp: new Date().toISOString(),
    context: context,
    errorCode: error.status?.code,
    errorDescription: error.status?.description,
    errorDetail: error.status?.detail,
    externalId: error.externalId,
    httpStatus: error.httpStatus
  };
  
  console.error('Localpayment API Error:', logEntry);
  // Send to your monitoring system
  sendToMonitoring(logEntry);
}
```

### Mensagens de erro fáceis de usar

Crie um mapeamento de códigos de erro técnicos para mensagens amigáveis ao usuário:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
const errorMessages = {
  '300': 'Please check your information and try again.',
  '701': 'Your payment was declined. Please use a different payment method.',
  '702': 'Payment authorization expired. Please try again.',
  '703': 'Temporary system issue. Please try again in a few minutes.',
  'default': 'An unexpected error occurred. Please contact support.'
};

function getUserMessage(errorCode) {
  return errorMessages[errorCode] || errorMessages['default'];
}
```

### Mecanismo de Repetição com Recuo Exponencial

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
async function makeRequestWithRetry(apiCall, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      // Only retry on certain errors
      if (!isRetryableError(error)) {
        throw error;
      }
      
      if (attempt === maxRetries) {
        throw error;
      }
      
      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

function isRetryableError(error) {
  const retryableCodes = ['500', '502', '503', '504', '800'];
  return retryableCodes.includes(error.status?.code);
}
```

### Padrão de disjuntor

Implemente um disjuntor para evitar falhas em cascata:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
class CircuitBreaker {
  constructor(failureThreshold = 5, resetTimeout = 60000) {
    this.failureThreshold = failureThreshold;
    this.resetTimeout = resetTimeout;
    this.failureCount = 0;
    this.lastFailureTime = null;
    this.state = 'CLOSED';
  }
  
  async call(apiFunction) {
    if (this.state === 'OPEN') {
      if (Date.now() - this.lastFailureTime > this.resetTimeout) {
        this.state = 'HALF_OPEN';
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }
    
    try {
      const result = await apiFunction();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
  
  onSuccess() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }
  
  onFailure() {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    
    if (this.failureCount >= this.failureThreshold) {
      this.state = 'OPEN';
    }
  }
}
```

***

## Próximos passos

> [card] [Referência da API](https://docs.localpayment.com/pt-br/reference/api-basics.md)
>
> Lista completa de códigos de erro com explicações detalhadas.

> [card] [Guia de Testes](https://docs.localpayment.com/pt-br/docs/testing.md)
>
> Aprenda como testar cenários de erro em um ambiente de sandbox.

> [card] [Contato de suporte](mailto:support@localpayment.com)
>
> Obtenha ajuda para cenários de erro específicos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.