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" }
}| Campo | Descrição |
|---|---|
error.code | Código estável. A lista completa está abaixo. |
error.message | Mensagem em português, segura para mostrar. |
error.issues | Só 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.details | Só em alguns erros: dados para seguir o fluxo. Em payment_declined, traz o pedido criado, o pagamento recusado, o accessToken e a orderUrl. |
error.requestId | Identificador da requisição. Envie ao suporte junto com o horário. |
errors | A 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
| Status | O que fazer |
|---|---|
400, 413, 422 | Corrija a requisição. Repetir igual vai falhar de novo. |
401, 403 | Confira a chave, o tipo e os escopos. Não repita sem corrigir. |
402 | Pagamento recusado. O pedido continua aguardando pagamento: peça outra forma de pagamento e pague de novo. |
404 | O recurso não existe nesta loja (ou o carrinho expirou). |
409 | Conflito de estado. Consulte o recurso de novo antes de decidir. |
429 | Espere o tempo de Retry-After e repita. |
500, 502, 503 | Repita 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ódigo | Status | Mensagem | O que fazer |
|---|---|---|---|
unauthenticated | 401 | Autenticação necessária. | Envie a chave em Authorization: Bearer <chave>. |
invalid_api_key | 401 | Chave 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. |
forbidden | 403 | Você 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_scope | 403 | A 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ódigo | Status | Mensagem | O que fazer |
|---|---|---|---|
invalid_json | 400 | O corpo da requisição não é um JSON válido. | Confira o JSON e o Content-Type: application/json. |
payload_too_large | 413 | O corpo da requisição é grande demais. | O limite é 64 KB. Divida a operação. |
validation_failed | 422 | Os 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_found | 404 | Recurso não encontrado. | Confira o id. Recursos de outra loja também respondem 404. |
conflict | 409 | O 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_conflict | 409 | Esta chave de idempotência já foi usada com outros dados. | Gere uma Idempotency-Key nova para uma operação diferente. |
rate_limited | 429 | Muitas requisições. Aguarde um momento e tente novamente. | Espere o tempo de Retry-After. Veja Limites de requisição. |
Loja
| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
project_restricted | 403 | Esta loja está com restrições por pendência de faturamento. Regularize a fatura para continuar. | Pague a fatura em aberto. Veja Fatura vencida. |
checkout_paused | 403 | O 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ódigo | Status | Mensagem | O que fazer |
|---|---|---|---|
cart_not_found | 404 | Carrinho não encontrado ou expirado. Monte o carrinho de novo. | Crie outro carrinho. Também aparece sem o X-Cart-Token certo. |
cart_empty | 422 | O carrinho está vazio. | Adicione itens antes do checkout. |
cart_already_checked_out | 409 | Este 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_unavailable | 422 | Um dos produtos não está mais disponível para compra. | Remova o item e mostre o carrinho atualizado. |
out_of_stock | 409 | Não há estoque suficiente para um dos itens do carrinho. | Diminua a quantidade ou remova o item. |
coupon_invalid | 422 | Cupom inválido, expirado ou esgotado. | Remova o cupom (DELETE /carts/{cartId}/coupon) e mostre o novo total. |
coupon_not_applicable | 422 | Este cupom não vale para os itens do carrinho. | Mostre a mensagem; o cupom não se aplica a esses produtos. |
checkout_blocked | 403 | Nã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_payable | 409 | Este pedido não aceita mais pagamento. | O pedido foi pago, cancelado ou expirou. Consulte o pedido. |
Pagamento e reembolso
| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
payment_method_unavailable | 422 | Esta 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_declined | 402 | O 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_unavailable | 502 | O 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_allowed | 422 | Este 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_exceeded | 422 | O valor do reembolso é maior que o saldo disponível do pagamento. | Consulte amount e refundedAmount do pagamento e ajuste o valor. |
Entregas
| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
delivery_already_finalized | 409 | Esta 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ódigo | Status | Mensagem |
|---|---|---|
invalid_pairing_code | 400 | Código de pareamento inválido. |
pairing_code_expired | 410 | O código de pareamento expirou. Gere um novo no painel. |
server_token_revoked | 401 | O token do servidor foi revogado. Pareie o servidor novamente. |
server_paused | 423 | Este servidor está pausado no painel da MinePag. As entregas voltam quando ele for reativado. |
invalid_link_code | 400 | Código de vínculo inválido ou expirado. |
invalid_player_name | 422 | Nick de jogador inválido. |
plugin_outdated | 426 | A versão do plugin está desatualizada. Atualize para continuar. |
invalid_webhook_signature | 401 | Assinatura do webhook inválida. |
Veja Plugin Minecraft para os problemas de pareamento.
Servidor
| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
internal_error | 500 | Ocorreu um erro inesperado. Tente novamente em instantes. | Repita com espera. Se continuar, envie o requestId ao suporte. |
service_unavailable | 503 | Serviço temporariamente indisponível. Tente novamente em instantes. | Repita com espera. |