logo
ReferênciaErros Comuns

Erros Comuns

Diagnóstico e resolução dos erros mais frequentes

Visão geral

Este guia ajuda a diagnosticar e resolver os erros mais comuns ao integrar com a API Conta Simples. Os erros são organizados por categoria de código HTTP.

Antes de contatar o suporte, use o Checklist de diagnóstico no final desta página.

Erros da API por endpoint

GET /statements/v1/credit-card

O endpoint de extrato de transações pode retornar:

CódigoDescriçãoCausa comum
200OKSucesso
400Bad RequestParâmetros inválidos
500Internal Server ErrorErro interno

GET /attachments/v1/content/{attachmentId}

O endpoint de download de anexos pode retornar:

CódigoDescriçãoCausa comum
200OKSucesso (retorna binário)
404Not FoundAnexo não existe

Erros de validação (400)

Sintomas

  • 400 Bad Request
  • Parâmetros inválidos no body da requisição

Causas específicas para GET /statements/v1/credit-card

Erros de autenticação (401)

Sintomas

  • 401 Unauthorized
  • Mensagens como "Token inválido", "Token expirado", "Não autorizado"

Causas e soluções

Padrão de retry para 401

async function requestWithAuthRetry(
  method: string,
  url: string,
  options: RequestInit & { headers: Record<string, string> },
): Promise<Response> {
  let response = await fetch(url, { method, ...options });

  if (response.status === 401) {
    // Invalida cache do token
    invalidateTokenCache();

    // Obtém novo token
    const newToken = await getFreshToken();

    // Repete a requisição
    options.headers["Authorization"] = `Bearer ${newToken}`;
    response = await fetch(url, { method, ...options });
  }

  return response;
}

Erros de permissão (403)

Sintomas

  • 403 Forbidden
  • Mensagens como "Sem permissão", "Acesso negado"

Causas e soluções

Erros de recurso (404)

Sintomas

  • 404 Not Found
  • Recurso não encontrado

Causas específicas para GET /attachments/v1/content/{attachmentId}

Erros de servidor (500)

Sintomas

  • 500 Internal Server Error
  • Erro inesperado no servidor

Solução

Aguarde e tente novamente

Erros 500 podem ser transitórios. Aguarde alguns segundos e repita.

Implemente retry com backoff

Use backoff exponencial para evitar sobrecarregar o servidor.

Registre o timestamp e dados

Anote quando ocorreu e quais parâmetros enviou.

Contate o suporte se persistir

Se o erro persistir após 3-5 tentativas, abra um chamado.

Padrão de retry para 500

const RETRYABLE_STATUS = new Set([500, 502, 503, 504]);

async function requestWithRetry(
  method: string,
  url: string,
  maxRetries = 3,
  options?: RequestInit,
): Promise<Response> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const controller = new AbortController();
      const timeout = setTimeout(() => controller.abort(), 30_000);

      const response = await fetch(url, {
        method,
        ...options,
        signal: controller.signal,
      });
      clearTimeout(timeout);

      if (!RETRYABLE_STATUS.has(response.status)) {
        return response;
      }
    } catch (err) {
      if (!(err instanceof DOMException && err.name === "AbortError"))
        throw err;
    }

    if (attempt < maxRetries - 1) {
      const waitTime = 2 ** attempt + Math.random();
      await new Promise((resolve) => setTimeout(resolve, waitTime * 1000));
    }
  }

  throw new Error("Max retries exceeded");
}

Checklist de diagnóstico

Antes de contatar o suporte, verifique:

  • URL base está correta para o ambiente (Sandbox/Produção)
  • Token não expirou (válido por 30 minutos)
  • Header Authorization está no formato Bearer {TOKEN}
  • Header Content-Type é application/json
  • Body JSON está bem formado
  • Datas estão no formato YYYY-MM-DD
  • Período não excede 62 dias
  • Limit está entre 5 e 100
  • Tentou novamente após alguns segundos (para erros 5xx)

Informações para o suporte

Ao contatar o suporte, sempre inclua:

InformaçãoDescriçãoExemplo
TimestampData/hora exata (UTC)2025-01-15T14:30:00Z
AmbienteSandbox ou ProduçãoSandbox
EndpointURL e métodoGET /statements/v1/credit-card
Status codeCódigo HTTP retornado400
Request bodyPayload enviado (mascarado)Ver abaixo
Response bodyResposta da APIVer abaixo

Exemplo de payload mascarado para suporte

{
  "startDate": "2025-01-01",
  "endDate": "2025-01-31",
  "limit": 50
}

{
  "error": "Bad Request",
  "message": "startDate format is invalid"
}

Nunca inclua tokens, credenciais ou dados pessoais ao reportar problemas.

Quickstart

Revisitar passos iniciais.

Autenticação

Problemas com token ou credenciais.

API Reference

Referência técnica dos endpoints.

Dicionário de Dados

Descrição de todos os campos.

Was this page helpful?

Last updated today

Built with Documentation.AI