Catálogo de erros

Todo erro da API segue o mesmo envelope. Previsibilidade no formato de erro e o que permite escrever um unico tratador no seu codigo em vez de um por endpoint.

{
  "error": {
    "type": "card_error",
    "code": "insufficient_funds",
    "message": "Saldo ou limite insuficiente.",
    "param": "amount",
    "requestId": "req_01HQ8M5X7P2K3N4R5T6V7W8X9Y",
    "docsUrl": "https://docs.minstrel.com.br/errors/insufficient_funds",
    "meta": {}
  }
}

Guarde o requestId. Com ele, o suporte localiza a requisicao exata, com o corpo enviado e a resposta de cada conector acionado. Sem ele, a investigacao comeca do zero.

Tipos

O type e a categoria estavel: trate por ele, nao pela mensagem.

Observe a distincao entre card_error e connector_error: o primeiro e uma decisao do emissor (negocio), o segundo e uma falha tecnica. A diferenca muda completamente o que vale fazer em seguida.

Recusa na criacao do pagamento nao e erro HTTP. POST /v1/payments responde 201 com o pagamento em status: failed e o motivo em decline (classificacao ABECS, com retryAction): o pagamento existe e tem historico. O card_error (402) aparece nas operacoes sobre um pagamento existente - captura, cancelamento e estorno recusados pelo adquirente.

Codigos mais comuns

Teste de produção encerrado

production_subscription_required (403, authorization_error) indica que os 30 dias ou as 50 cobranças gratuitas terminaram, ou que a organização não tem plano nem teste ativo. O proprietário deve contratar um plano no painel. Sandbox, consultas e estornos de pagamentos existentes continuam disponíveis. Repetir a criação com outra chave não libera saldo.

Conta já cadastrada

registration_identity_in_use (409, conflict_error) aparece quando o CNPJ ou e-mail já pertence a um cadastro. Entre na conta existente ou procure o suporte. Alterar os dados da conta anterior não reinicia o teste.

Dados de cartao recusados

{
  "error": {
    "type": "invalid_request_error",
    "code": "raw_card_data_rejected",
    "param": "card.number",
    "meta": { "offendingPaths": ["card.number", "card.cvv"] }
  }
}

A API nao aceita numero de cartao, CVV, trilha ou PIN. Tokenize o cartao e envie apenas o token. O erro lista os caminhos dos campos, nunca os valores - caso contrario ele mesmo vazaria o dado para os seus logs.

A checagem tambem pega cartao colado em campo de texto livre, como description ou metadata.

Chave de idempotencia reutilizada

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_key_reused",
    "message": "Esta chave de idempotencia ja foi usada com um corpo de requisicao diferente. Gere uma nova chave para uma cobranca diferente."
  }
}

Este erro esta protegendo voce do bug mais perigoso da categoria: reaproveitar uma chave entre cobrancas distintas faria a segunda ser silenciosamente ignorada, e o cliente nao seria cobrado. Gere uma chave por operacao.

Requisicao em andamento

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_request_in_progress"
  }
}

Duas requisicoes com a mesma chave chegaram ao mesmo tempo. Aguarde alguns segundos e consulte o pagamento - nao crie outro.

Devolvemos 409 em vez da resposta parcial de proposito: tratar como sucesso algo que ainda pode falhar seria pior.

Nenhum conector disponivel

{
  "error": {
    "type": "connector_error",
    "code": "no_connector_available",
    "meta": { "requested": ["ca_..."] }
  }
}

Nenhuma conta de conector do fluxo esta habilitada e saudavel. Pode ser circuito aberto por falhas consecutivas: consulte o painel de conectores.

Fluxo nao publicado

{
  "error": {
    "type": "flow_error",
    "code": "flow_not_published",
    "message": "Ha mais de um conector habilitado e nenhum fluxo publicado. Publique um fluxo para definir o roteamento."
  }
}

Com um unico conector habilitado, roteamos direto. Com mais de um, escolher por voce seria adivinhar a intencao em algo que move dinheiro.

Checkout transparente

Erros das rotas do checkout transparente, que o @minstrel/js entrega como MinstrelError do tipo api:

Uma recusa do emissor nao e erro HTTP. Na simulacao do checkout, uma recusa reversivel devolve o pagamento em requires_payment_method com decline e cardAttempts (o comprador tenta outro cartao com o mesmo clientSecret, ate CHECKOUT_MAX_CARD_ATTEMPTS, padrao 3) e emite payment.attempt_declined; recusa irreversivel, limite de tentativas ou prazo encerram o pagamento como failed.

As rotas publicas (/v1/public/payments/...) tambem respondem 429 (rate_limit_error) com Retry-After: ha um teto por IP e, por pagamento, um teto de sessoes de tokenizacao e de confirmacoes por hora.

Antifraude da adquirente

Com o antifraude embutido da Cielo ligado, tres situacoes tem cara diferente:

Split nao suportado

{
  "error": {
    "type": "connector_error",
    "code": "split_not_supported",
    "message": "Este pagamento tem split, mas nenhuma conta candidata consegue executa-lo no adquirente. Cielo - principal (cielo): a conta \"Cielo - principal\" (cielo) nao executa split: ligue o recurso de split na configuracao da conta (Plugins). Autorizar sem dividir liquidaria o valor inteiro para o lojista principal, por isso o pagamento nao foi autorizado. Ligue o split na conta e registre cada recebedor nela (connectorAccountId e externalRecipientId).",
    "requestId": "req_01HQ...",
    "meta": {
      "blocked": [
        {
          "connectorAccountId": "ca_01HQ...",
          "name": "Cielo - principal",
          "connectorSlug": "cielo",
          "gaps": [{ "code": "account_without_split" }]
        }
      ]
    }
  }
}

Um pagamento com split so e autorizado numa conta que executa a divisao no adquirente e onde todos os recebedores estao registrados. Se nenhuma candidata serve, o pagamento nao e autorizado: autorizar sem dividir liquidaria o valor inteiro para o lojista principal.

O que fazer: ligue o recurso Split de pagamento na conta (Plugins, conta, Recursos) e registre cada recebedor nela, com connectorAccountId e externalRecipientId. Na Cielo, o id e o SubordinateMerchantId do seller.

Split na Cielo

Quando a Cielo barra uma venda de Split, o motivo e de configuracao (do Split, do recebedor ou do valor) e nunca do cartao. Por isso o Minstrel nao a trata como recusa do emissor: devolve connector_contract_violation (tipo connector_error), nao retentavel, sem fallback para outra conta, com a explicacao em portugues e o texto original da Cielo entre parenteses.

Tambem sao erro tecnico nao retentavel as credenciais do Split: Client Secret ausente com o split ligado, ou recusado pela Cielo, voltam connector_credentials_invalid, com a instrucao de onde gerar ou conferir (Conectores, Split da Cielo). E uma divisao fora do contrato (soma acima do valor, recebedor repetido ou id fora do formato GUID) volta connector_contract_violation antes de qualquer chamada a Cielo.

Tratando erros

import { Minstrel, MinstrelApiError } from '@minstrel/sdk';

try {
  const payment = await minstrel.payments.create({ amount: 14990 });
} catch (error) {
  if (!(error instanceof MinstrelApiError)) throw error;

  // Recusa do emissor: mostre a mensagem ao cliente.
  if (error.isCardError) {
    return mostrarAoCliente(error.message);
  }

  // Falha tecnica: pode ser retentada com a MESMA chave de idempotencia.
  if (error.isRetryable) {
    return agendarRetentativa();
  }

  // Erro de integracao: corrija o codigo.
  logger.error({ code: error.code, requestId: error.requestId }, error.message);
  throw error;
}

A regra geral: retente connector_error, rate_limit_error e api_error usando a mesma chave de idempotencia. Nao retente invalid_request_error nem card_error - no primeiro, a requisicao esta errada; no segundo, consulte decline.retryAction, que diz o que fazer.