Catalogo 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

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:

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.

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.