Ir para o conteúdo
Docs

Erros

Formato padrão dos erros, códigos HTTP e a tabela completa de códigos da API.

Formato

Todo erro usa o mesmo envelope e um status HTTP coerente: 4xx quando a requisição precisa mudar, 5xx quando o problema está na MaxxiPay ou no processamento PIX.

Campos do erro

  • errorobject
  • error.codestring

    Código estável, legível por máquina.

  • error.messagestring

    Explicação em português para quem integra.

  • error.fieldstring

    Campo que causou o erro, quando houver.

  • error.requestIdstring

    Identificador da requisição. Informe ao suporte.

Programe contra error.code, que é estável. O texto de error.message é escrito para pessoas e pode mudar.

RespostaJSON422 Unprocessable Entity
{
  "error": {
    "code": "invalid_body",
    "message": "Informe um CPF ou CNPJ válido.",
    "field": "payerDocument",
    "requestId": "req_Q2x8mZp4LkT7aV1c"
  }
}

Códigos

CódigoHTTPSignificadoO que fazer
invalid_json400O corpo não é um JSON válido.Envie JSON com Content-Type: application/json.
idempotency_key_required400Faltou o cabeçalho Idempotency-Key ou ele tem menos de 8 ou mais de 120 caracteres.Gere uma chave única por operação e envie no cabeçalho.
unauthenticated401A requisição chegou sem credencial.Envie Authorization: Bearer com a sua chave.
invalid_api_key401A chave não existe ou foi revogada.Confira a chave no cofre de segredos ou crie outra no painel.
forbidden403A chave não tem o escopo exigido pela rota.Use uma chave com o escopo indicado na referência.
api_key_not_allowed403A rota pertence ao painel e não aceita chave de API.Use só as rotas da referência pública.
origin_rejected403A requisição veio de um navegador com origem não autorizada.Chame a API a partir do seu servidor, nunca do navegador.
account_not_verified403A conta ainda não foi verificada. Cobranças e saques ficam bloqueados até a aprovação.Conclua a verificação da empresa no painel.
merchant_blocked403A conta está bloqueada. Cobranças e saques estão suspensos.Fale com a MaxxiPay.
not_found404O recurso não existe ou pertence a outra empresa.Confira o identificador.
idempotency_conflict409A Idempotency-Key já foi usada com outro conteúdo.Use uma chave nova para uma operação nova.
event_delivery_pending409O evento já está na fila de entrega.Aguarde a próxima tentativa ou consulte o evento.
payload_too_large413O corpo passou de 1 MB.Reduza o tamanho da requisição.
invalid_body422Um campo do corpo não passou na validação. O campo vem em error.field.Corrija o campo indicado e envie de novo. Erros de validação não consomem a Idempotency-Key.
invalid_query422Um parâmetro de consulta é inválido. O parâmetro vem em error.field.Corrija o parâmetro indicado.
invalid_cursor422O cursor não foi gerado pela API.Use exatamente o nextCursor da página anterior.
insufficient_balance422O saldo disponível não cobre o saque.Consulte o saldo antes de sacar. Para tentar de novo, use uma Idempotency-Key nova.
limit_per_charge422O valor passa do máximo por cobrança da conta. O padrão é R$ 10.000,00 e o valor em vigor vem em error.message.Divida o valor em mais de uma cobrança ou peça um limite maior à MaxxiPay.
limit_per_payout422O valor passa do máximo por saque da conta. O padrão é R$ 10.000,00 e o valor em vigor vem em error.message.Divida o valor em mais de um saque ou peça um limite maior à MaxxiPay.
rate_limited429A chave passou do limite de requisições por minuto.Espere os segundos de Retry-After e tente de novo.
internal500Erro inesperado na MaxxiPay.Tente de novo com a mesma Idempotency-Key. Se persistir, envie o requestId ao suporte.
processing_failed502O processamento PIX recusou a operação. O motivo vem em error.message e em failureReason.Revise os dados. Para tentar de novo, use uma Idempotency-Key nova.

Como tratar

  • Repita só 429, 500 e falhas de rede, com espera crescente e a mesma Idempotency-Key.
  • Em 422, mostre a mensagem ao usuário ou corrija o campo de error.field.
  • Em 502 processing_failed, o registro fica com status failed e o motivo em failureReason. Revise os dados antes de tentar com uma chave nova.
  • Registre o requestId de toda resposta com erro.
Nova tentativa com espera
const retryable = new Set([429, 500]);

async function send(request, attempt = 0) {
  const response = await fetch(request.url, request.init);
  if (!retryable.has(response.status) || attempt === 4) return response;
  const wait = Number(response.headers.get("retry-after") ?? 2 ** attempt);
  await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  return send(request, attempt + 1);
}
esc