Códigos de Erro

Referência completa dos códigos de status HTTP e tratamento de erros da API Versell Pix

Visão Geral

As APIs de Cash In e Cash Out da Versell retornam erros seguindo o padrão RFC 7807 (Problem Details for HTTP APIs). Cada resposta de erro inclui um objeto JSON com informações estruturadas sobre o problema, facilitando o diagnóstico e o tratamento programático de erros.

Formato da Resposta de Erro

Todas as respostas de erro seguem a estrutura abaixo:

{
  "type": "https://pix.bcb.gov.br/api/v2/error/CobOperacaoInvalida",
  "title": "Cobranca invalida",
  "status": 400,
  "detail": "A cobranca informada apresenta inconsistencias.",
  "violacoes": [
    {
      "razao": "O campo valor.original deve ser maior que zero",
      "propriedade": "valor.original"
    }
  ]
}

Campo	Tipo	Descrição
`type`	string	URI que identifica o tipo de erro
`title`	string	Título legível do erro
`status`	integer	Código de status HTTP
`detail`	string	Descrição detalhada do erro
`violacoes`	array	Lista de violações de validação (opcional)

Códigos de Status HTTP

A tabela abaixo lista todos os códigos de status retornados pelas APIs:

Status	Nome	Quando Ocorre	Solução
`400`	Bad Request	Parâmetros inválidos, corpo malformado ou campos obrigatórios ausentes	Verifique o corpo da requisição e os parâmetros
`401`	Unauthorized	Token expirado, inválido ou ausente	Solicite um novo token de acesso
`403`	Forbidden	Certificado mTLS ausente ou inválido, escopo insuficiente	Verifique o certificado e os escopos
`404`	Not Found	Recurso não existe (txid, e2eid, webhook, etc.)	Verifique se o ID ou chave informado existe
`405`	Method Not Allowed	Método HTTP incorreto para o endpoint	Verifique o método correto na documentação
`409`	Conflict	Recurso já existe ou conflito de estado	Verifique o estado atual do recurso
`412`	Precondition Failed	Requisição conflita com o estado do servidor	Verifique as pré-condições da operação
`422`	Unprocessable Entity	Dados semanticamente inválidos (ex: reembolso excede valor original)	Corrija a lógica de negócio da requisição
`429`	Too Many Requests	Rate limit excedido (endpoint de token: 10 req/min)	Faça cache dos tokens e implemente backoff exponencial
`500`	Internal Server Error	Erro interno do servidor	Tente novamente com backoff exponencial
`503`	Service Unavailable	Serviço temporariamente indisponível	Aguarde e tente novamente após alguns segundos
`504`	Gateway Timeout	Timeout do upstream (apenas Cash Out)	Tente novamente a requisição

Para erros 5xx (500, 503, 504), sempre implemente retry com backoff exponencial. Nunca faça retry imediato em loops, pois isso pode agravar o problema.

Array de Violações

Quando a API retorna um erro 400, o campo violacoes pode conter uma lista de erros de validação a nível de campo. Cada objeto na lista possui dois campos:

Campo	Descrição
`razao`	Motivo da violação — descreve o que está errado com o campo
`propriedade`	Nome da propriedade/campo que causou o erro (ex: valor.original, chave)

{
  "type": "https://pix.bcb.gov.br/api/v2/error/CobOperacaoInvalida",
  "title": "Cobranca invalida",
  "status": 400,
  "detail": "A cobranca nao respeita o schema.",
  "violacoes": [
    {
      "razao": "O campo valor.original deve ser maior que zero",
      "propriedade": "valor.original"
    },
    {
      "razao": "O campo chave nao e uma chave Pix valida",
      "propriedade": "chave"
    }
  ]
}

Use o array violacoes para exibir mensagens de erro específicas ao usuário final, mapeando cada propriedade ao campo correspondente no formulário.

Cenários Comuns de Erro

Erros de Token

Cenário	Status	Solução
Token expirado	`401`	Solicite um novo token antes que o atual expire (Cash In: 300s, Cash Out: 3600s)
Credenciais inválidas (client_id/client_secret)	`401`	Verifique as credenciais no painel Finance
Rate limit no endpoint de token (10 req/min)	`429`	Faça cache do token e renove apenas próximo da expiração

Erros de Certificado

Cenário	Status	Solução
Falha no handshake mTLS	`403`	Confirme que o certificado .crt/.pfx está sendo enviado na requisição
Certificado de Cash In usado no Cash Out (ou vice-versa)	`403`	Use o certificado correto para cada módulo — são diferentes
Certificado expirado ou revogado	`403`	Solicite um novo certificado à Versell

Cash In e Cash Out utilizam certificados mTLS DIFERENTES. Usar o certificado errado resultará em erro 403 Forbidden.

Erros de Idempotência

Cenário	Status	Solução
Chave de idempotência duplicada com payload diferente	`409`	Gere uma nova chave de idempotência (UUID v4) para cada requisição única
Chave de idempotência duplicada com mesmo payload	`200`	Comportamento correto — a API retorna a resposta original (seguro para retry)

Erros Específicos do Pix

Cenário	Status	Solução
Valor da cobrança igual a zero ou negativo	`400`	O campo valor.original deve ser maior que zero (ex: "10.00")
Tipo de chave Pix inválido	`400`	Use um dos tipos válidos: CPF, CNPJ, telefone (+5511...), e-mail ou chave aleatória
Reembolso excede o valor original do Pix	`422`	O valor do reembolso não pode ser maior que o valor recebido
txid ou e2eid não encontrado	`404`	Verifique se o identificador está correto e se a transação existe

Tratamento de Erros em Código

Exemplo de como tratar erros da API de forma robusta com Node.js e Axios:

const axios = require('axios');

async function createCharge(token, chargeData) {
  try {
    const response = await axios.post(
      'https://api.pix.basspago.com.br/cob',
      chargeData,
      {
        headers: {
          Authorization: `Bearer ${token}`,
          'Content-Type': 'application/json',
        },
        httpsAgent: agent, // mTLS agent
      }
    );
    return response.data;
  } catch (error) {
    if (error.response) {
      const { status, data } = error.response;

      switch (status) {
        case 400:
          console.error('Validation error:', data.detail);
          if (data.violacoes) {
            data.violacoes.forEach((v) => {
              console.error(`  Field "${v.propriedade}": ${v.razao}`);
            });
          }
          break;
        case 401:
          console.error('Token expired — requesting new token...');
          // Implement token refresh logic
          break;
        case 403:
          console.error('Certificate error:', data.detail);
          break;
        case 429:
          const retryAfter = error.response.headers['retry-after'] || 60;
          console.error(`Rate limited. Retry after ${retryAfter}s`);
          break;
        case 500:
        case 503:
        case 504:
          console.error('Server error — retrying with backoff...');
          // Implement exponential backoff retry
          break;
        default:
          console.error(`Unexpected error ${status}:`, data);
      }
    } else {
      console.error('Network error:', error.message);
    }
    throw error;
  }
}

Sempre faça cache dos tokens de acesso e implemente lógica de retry com backoff exponencial para erros 5xx. Para erros 4xx, corrija a requisição antes de tentar novamente.