Referência

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

POST /statements/v1/credit-card

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

Código	Descrição	Causa comum
`200`	OK	Sucesso
`400`	Bad Request	Parâmetros inválidos
`500`	Internal Server Error	Erro interno

GET /attachments/v1/content/`{attachmentId}`

O endpoint de download de anexos pode retornar:

Código	Descrição	Causa comum
`200`	OK	Sucesso (retorna binário)
`404`	Not Found	Anexo 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 POST /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", "Escopo insuficiente"

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 1 hora)
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ção	Descrição	Exemplo
Timestamp	Data/hora exata (UTC)	`2025-01-15T14:30:00Z`
Ambiente	Sandbox ou Produção	`Sandbox`
Endpoint	URL e método	`POST /statements/v1/credit-card`
Status code	Código HTTP retornado	`400`
Request body	Payload enviado (mascarado)	Ver abaixo
Response body	Resposta da API	Ver 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.

Links úteis

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