Tratamento de Erros

Copiar

• Copiar para LLM

  Copiar página como Markdown para LLMs
• Ver como Markdown

  Abrir esta página como Markdown
• Abrir no ChatGPT

  Obter informações do ChatGPT
• Abrir no Claude

  Obter informações do Claude

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

Formato de Resposta de Erro

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

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)
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 - Aprenda sobre retentativas seguras com chaves de idempotência
• Autenticação - Corrija erros de autenticação
• Início Rápido - Faça a sua primeira chamada bem-sucedida à API