Desenvolvedores

Erros da API

Formato dos erros, todos os códigos com status HTTP e o que fazer em cada caso.

Quando algo dá errado, a API responde com um status HTTP de erro e um código estável em error.code. Use o código para decidir o que fazer no seu sistema; a mensagem está em português e pode ser mostrada a quem usa o seu sistema, mas o texto pode mudar.

Formato do erro

{
  "data": null,
  "error": {
    "code": "validation_failed",
    "message": "Os dados enviados são inválidos.",
    "issues": [
      { "path": "buyer.document", "message": "O boleto exige CPF ou CNPJ." },
      { "path": "payment.billingAddress", "message": "O boleto exige o endereço de cobrança." }
    ],
    "requestId": "5b0f7a52-0d8e-4b51-9a57-1f0c6b7e2d10"
  },
  "errors": [
    { "code": "validation_failed", "message": "O boleto exige CPF ou CNPJ.", "path": "buyer.document" },
    { "code": "validation_failed", "message": "O boleto exige o endereço de cobrança.", "path": "payment.billingAddress" }
  ],
  "meta": { "requestId": "5b0f7a52-0d8e-4b51-9a57-1f0c6b7e2d10" }
}
CampoDescrição
error.codeCódigo estável. A lista completa está abaixo.
error.messageMensagem em português, segura para mostrar.
error.issuesSó em erros de validação: um item por campo, com o caminho (path) e a mensagem. Caminhos aninhados usam ponto, como buyer.email ou items.0.quantity.
error.detailsSó em alguns erros: dados para seguir o fluxo. Em payment_declined, traz o pedido criado, o pagamento recusado, o accessToken e a orderUrl.
error.requestIdIdentificador da requisição. Envie ao suporte junto com o horário.
errorsA mesma informação em lista, com um item por problema.

O cabeçalho X-Request-Id traz o mesmo identificador. Em 429, o cabeçalho Retry-After diz quantos segundos esperar.

Como tratar

StatusO que fazer
400, 413, 422Corrija a requisição. Repetir igual vai falhar de novo.
401, 403Confira a chave, o tipo e os escopos. Não repita sem corrigir.
402Pagamento recusado. O pedido continua aguardando pagamento: peça outra forma de pagamento e pague de novo.
404O recurso não existe nesta loja (ou o carrinho expirou).
409Conflito de estado. Consulte o recurso de novo antes de decidir.
429Espere o tempo de Retry-After e repita.
500, 502, 503Repita com espera crescente (ex.: 1 s, 2 s, 4 s). Em operações com Idempotency-Key, use a mesma chave e o mesmo corpo: respostas 5xx não ficam guardadas, então a repetição executa de verdade.
async function callMinePag(path, init, attempt = 1) {
  const response = await fetch(`https://minepag.com.br/api/v1${path}`, init);
  if (response.ok) return response.json();

  const { error } = await response.json();
  const retryable = response.status === 429 || response.status >= 500;
  if (retryable && attempt < 4) {
    const waitSeconds = Number(response.headers.get('Retry-After')) || 2 ** (attempt - 1);
    await new Promise(resolve => setTimeout(resolve, waitSeconds * 1000));
    return callMinePag(path, init, attempt + 1);
  }
  throw Object.assign(new Error(error.message), { code: error.code, issues: error.issues, requestId: error.requestId });
}

Códigos

Autenticação e permissão

CódigoStatusMensagemO que fazer
unauthenticated401Autenticação necessária.Envie a chave em Authorization: Bearer <chave>.
invalid_api_key401Chave de API inválida, expirada ou revogada.Confira se a chave foi copiada inteira e se não foi revogada ou expirou. Crie outra se preciso.
forbidden403Você não tem permissão para executar esta ação.A mensagem diz o motivo: chave secreta usada no navegador (com Origin) ou rota que exige chave secreta.
insufficient_scope403A chave de API não tem o escopo necessário para esta operação.A mensagem diz qual escopo falta. Crie uma chave com esse escopo.

Requisição

CódigoStatusMensagemO que fazer
invalid_json400O corpo da requisição não é um JSON válido.Confira o JSON e o Content-Type: application/json.
payload_too_large413O corpo da requisição é grande demais.O limite é 64 KB. Divida a operação.
validation_failed422Os dados enviados são inválidos.Veja error.issues e corrija cada campo. Também vale para cabeçalhos, como Idempotency-Key ausente ou inválido, e para cursor de paginação inválido.
not_found404Recurso não encontrado.Confira o id. Recursos de outra loja também respondem 404.
conflict409O recurso foi alterado por outra operação. Tente novamente.Consulte o recurso de novo. Também aparece quando uma chamada com a mesma Idempotency-Key ainda está em andamento, e ao cancelar um pedido que não está aguardando pagamento.
idempotency_conflict409Esta chave de idempotência já foi usada com outros dados.Gere uma Idempotency-Key nova para uma operação diferente.
rate_limited429Muitas requisições. Aguarde um momento e tente novamente.Espere o tempo de Retry-After. Veja Limites de requisição.

Loja

CódigoStatusMensagemO que fazer
project_restricted403Esta loja está com restrições por pendência de faturamento. Regularize a fatura para continuar.Pague a fatura em aberto. Veja Fatura vencida.
checkout_paused403O checkout desta loja está temporariamente pausado.O checkout foi pausado por fatura vencida ou pelo limite rígido de gastos. Mostre a mensagem ao comprador.

Carrinho e checkout

CódigoStatusMensagemO que fazer
cart_not_found404Carrinho não encontrado ou expirado. Monte o carrinho de novo.Crie outro carrinho. Também aparece sem o X-Cart-Token certo.
cart_empty422O carrinho está vazio.Adicione itens antes do checkout.
cart_already_checked_out409Este carrinho já virou um pedido. Consulte o pedido gerado.Não repita o checkout com outra chave. Crie outro carrinho para uma nova compra.
product_unavailable422Um dos produtos não está mais disponível para compra.Remova o item e mostre o carrinho atualizado.
out_of_stock409Não há estoque suficiente para um dos itens do carrinho.Diminua a quantidade ou remova o item.
coupon_invalid422Cupom inválido, expirado ou esgotado.Remova o cupom (DELETE /carts/{cartId}/coupon) e mostre o novo total.
coupon_not_applicable422Este cupom não vale para os itens do carrinho.Mostre a mensagem; o cupom não se aplica a esses produtos.
checkout_blocked403Não foi possível concluir a compra. Se o problema continuar, fale com a loja.A proteção de checkout barrou a compra. Não repita automaticamente.
order_not_payable409Este pedido não aceita mais pagamento.O pedido foi pago, cancelado ou expirou. Consulte o pedido.

Pagamento e reembolso

CódigoStatusMensagemO que fazer
payment_method_unavailable422Esta forma de pagamento não está disponível nesta loja.Ofereça outra forma. A loja precisa de uma rota de pagamento para essa forma.
payment_declined402O pagamento foi recusado. Confira os dados ou use outra forma de pagamento.O pedido foi criado e continua aguardando pagamento. error.details traz o pedido, o pagamento recusado (com failureReason), o accessToken e a orderUrl. Peça outro cartão ou outra forma de pagamento e chame POST /orders/{orderId}/payments com o accessToken no cabeçalho X-Order-Token.
payment_provider_unavailable502O gateway de pagamento não respondeu. Tente novamente em instantes.No checkout e na nova tentativa de pagamento, o pedido já existe: error.details traz order, payment (pendente, sem cobrança), accessToken e orderUrl. Não monte outro carrinho. Repita o checkout com a mesma Idempotency-Key e o mesmo corpo, ou pague pelo pedido em POST /orders/{orderId}/payments com o accessToken no cabeçalho X-Order-Token. Veja Gateway fora do ar e nova tentativa.
refund_not_allowed422Este pagamento não pode ser reembolsado.A mensagem traz o motivo do gateway. Pagamentos não confirmados não são reembolsáveis.
refund_amount_exceeded422O valor do reembolso é maior que o saldo disponível do pagamento.Consulte amount e refundedAmount do pagamento e ajuste o valor.

Entregas

CódigoStatusMensagemO que fazer
delivery_already_finalized409Esta entrega já foi finalizada.A entrega já foi confirmada, cancelada ou esgotou as tentativas. Não precisa repetir.

Plugin Minecraft e webhooks recebidos

Estes códigos usam o mesmo formato, mas aparecem na comunicação do plugin Minecraft e nos webhooks que os gateways enviam à MinePag, não na API v1.

CódigoStatusMensagem
invalid_pairing_code400Código de pareamento inválido.
pairing_code_expired410O código de pareamento expirou. Gere um novo no painel.
server_token_revoked401O token do servidor foi revogado. Pareie o servidor novamente.
server_paused423Este servidor está pausado no painel da MinePag. As entregas voltam quando ele for reativado.
invalid_link_code400Código de vínculo inválido ou expirado.
invalid_player_name422Nick de jogador inválido.
plugin_outdated426A versão do plugin está desatualizada. Atualize para continuar.
invalid_webhook_signature401Assinatura do webhook inválida.

Veja Plugin Minecraft para os problemas de pareamento.

Servidor

CódigoStatusMensagemO que fazer
internal_error500Ocorreu um erro inesperado. Tente novamente em instantes.Repita com espera. Se continuar, envie o requestId ao suporte.
service_unavailable503Serviço temporariamente indisponível. Tente novamente em instantes.Repita com espera.

Nesta página