Começar

Erros

Todo erro tem o mesmo formato. error é estável e pode ser usado no seu código; message é texto para pessoas e pode mudar. Guarde o request_id para falar com o suporte.

Formato

{
  "error": "invalid_request",
  "message": "Algum campo está ausente, sobrando ou com formato inválido.",
  "doc_url": "https://mainumpay.com/docs/erros#invalid_request",
  "request_id": "req_0192a7c4-5b20-7c11-8e4f-2b9d0c6a3e58"
}

Alguns erros trazem campos extras: operation_limit_exceeded traz reasons, destination_ownership_not_verified traz reason e charge_creation_in_progress traz charge_id.

Catálogo de códigos

HTTP	error	O que aconteceu	O que fazer
404	`checkout_session_not_found`	Não há sessão de checkout com esse ID nesta conta.	Confira o ID e o ambiente da chave.
422	`store_unavailable`	A loja informada não existe nesta conta ou não está ativa.	Confira o store_id no painel (Lojas) e se a loja não está pausada ou arquivada.
422	`checkout_amount_mismatch`	O total informado difere da soma dos itens.	Confira quantidades e preços atuais dos produtos antes de criar a sessão.
400	`invalid_request`	Algum campo está ausente, sobrando ou com formato inválido.	Compare o corpo e a query com o contrato do endpoint e corrija o campo.
400	`invalid_json`	O corpo não é um JSON válido.	Envie JSON válido com Content-Type: application/json.
400	`idempotency_key_required`	Faltou o cabeçalho Idempotency-Key.	Envie um valor único de 8 a 128 caracteres visíveis para cada operação.
400	`invalid_pix_key`	A chave Pix não corresponde ao tipo informado.	Confira pix_key.type e pix_key.value.
400	`invalid_cursor`	O cursor de paginação é inválido.	Use o next_cursor devolvido pela página anterior ou recomece sem cursor.
401	`invalid_api_key`	A chave está ausente, revogada, expirada, é de outro ambiente ou não tem o escopo exigido.	Confira o prefixo gw_test_ ou gw_live_ e os escopos da chave no painel.
403	`merchant_not_operational`	A conta ainda não pode criar cobranças.	Conclua a verificação da conta no painel.
403	`card_unavailable`	Cobrança no cartão ainda não está disponível.	Use Pix por enquanto; o cartão será liberado em uma próxima versão.
403	`card_not_enabled`	Cobrança no cartão não está liberada para esta conta.	Fale com o suporte para liberar o cartão.
403	`withdrawal_not_permitted`	A conta não pode sacar agora.	Confira a verificação bancária e os bloqueios da conta no painel.
403	`external_withdrawal_scope_required`	O saque vai para um documento diferente do da conta.	Use uma chave com o escopo withdrawals:external_write, liberado pelo admin.
404	`product_not_found`	Não há produto com esse ID nesta conta.	Confira o ID em GET /v1/products.
404	`charge_not_found`	Não há cobrança com esse ID nesta conta.	Confira o ID e o ambiente da chave.
404	`withdrawal_not_found`	Não há saque com esse ID nesta conta.	Confira o ID e o ambiente da chave.
404	`med_case_not_found`	Não há caso MED com esse ID nesta conta.	Confira o ID e o ambiente da chave.
404	`event_not_found`	Não há evento com esse ID nesta conta.	Confira o ID; eventos internos não são listados.
404	`not_found`	Rota inexistente.	Confira o método e o caminho.
409	`external_id_conflict`	Já existe um recurso com este external_id.	Use outro external_id ou consulte o recurso existente.
409	`idempotency_conflict`	A mesma Idempotency-Key já foi usada com outro corpo.	Gere uma chave nova para cada operação diferente.
409	`charge_creation_in_progress`	Esta cobrança ainda está sendo criada.	Consulte GET /v1/charges/{charge_id} em alguns segundos.
422	`product_unavailable`	O produto não pode ser cobrado assim.	Veja reason: not_found, inactive (arquivado, desativado ou plano de assinatura) ou price_mismatch (amount_cents diferente do preço atual).
422	`charge_rejected`	O valor não é aceito pelas tarifas e limites da conta.	Se reasons indicar o valor, use minimum_amount_cents e maximum_amount_cents; senão, confira as tarifas no painel.
422	`withdrawal_rejected`	O saque não é aceito pelas tarifas e limites da conta.	Se reasons indicar o valor, use minimum_amount_cents e maximum_amount_cents; senão, confira as tarifas no painel.
422	`insufficient_withdrawable_balance`	O saldo sacável não cobre o valor e a tarifa.	Consulte GET /v1/balance e ajuste o valor.
422	`withdrawal_limit_exceeded`	O saque passa do limite diário.	Reduza o valor ou tente depois.
422	`destination_ownership_not_verified`	Ainda não confirmamos que o destino pertence à conta.	Aguarde a verificação ou use a chave cadastrada no painel.
429	`rate_limit_exceeded`	Muitas chamadas em pouco tempo.	Espere o tempo do cabeçalho Retry-After.
429	`operation_limit_exceeded`	Um limite de operação da conta foi atingido.	Veja reasons e ajuste o valor ou aguarde a janela.
503	`service_unavailable`	Instabilidade temporária.	Repita com a mesma Idempotency-Key; nada é criado em dobro.
500	`internal_error`	Erro inesperado.	Repita com a mesma Idempotency-Key e informe o request_id ao suporte se persistir.