Referência

Códigos de Erro HTTP

A API utiliza códigos de status HTTP padrão para indicar o resultado de cada requisição. Cada resposta de erro inclui uma mensagem descritiva para facilitar o diagnóstico.

Códigos HTTP Utilizados

200

Requisição processada com sucesso. Os dados estão no campo data.

400

Bad Request

A requisição é inválida ou malformada.

Parâmetros obrigatórios ausentes
Valores ou formatos de campos inválidos
JSON malformado no corpo da requisição
Regras de negócio violadas (ex: valor abaixo do mínimo)

401

Unauthorized

Falha na autenticação.

Header api-secret ausente
API Secret inválido ou revogado
API Secret pertence a ambiente diferente

403

Forbidden

Acesso negado. O recurso existe mas você não tem permissão.

Recurso pertence a outro usuário
Funcionalidade não habilitada para sua conta
Conta bloqueada ou com restrições

404

Not Found

O recurso solicitado não foi encontrado.

URL do endpoint inválida
ID do recurso não existe
Recurso foi removido

429

Too Many Requests

Limite de requisições atingido. Aguarde antes de tentar novamente.

Rate limit por minuto excedido
Operação paralela em andamento (ex: transferência sendo processada)

500

Internal Server Error

Erro inesperado em nossos servidores. Tente novamente ou contate o suporte.

Tratamento de Erros

Exemplo em JavaScriptjavascript

async function criarTransacao(payload) {
  try {
    const response = await fetch('/v1/transactions', {
      method: 'POST',
      headers: {
        'api-secret': process.env.API_SECRET,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });

    const data = await response.json();

    if (!response.ok || !data.success) {
      const errorMessage = data.error?.message || 'Erro desconhecido';
      
      switch (response.status) {
        case 400:
          throw new Error(`Dados inválidos: ${errorMessage}`);
        case 401:
          throw new Error('API Secret inválida ou ausente');
        case 429:
          throw new Error('Rate limit atingido. Aguarde e tente novamente.');
        default:
          throw new Error(`Erro ${response.status}: ${errorMessage}`);
      }
    }

    return data.data;
  } catch (error) {
    console.error('Erro na requisição:', error.message);
    throw error;
  }
}

Dica de debugging

Todos os erros incluem o campo error.message com uma descrição em português do problema. Use estas mensagens para identificar rapidamente a causa do erro durante a integração.