Erros

Toda resposta de erro tem o mesmo formato, com um código que não muda.

400

{
  "erro": {
    "codigo": "requisicao_invalida",
    "mensagem": "Corpo da requisição inválido.",
    "detalhes": [{ "campo": "valorCentavos", "mensagem": "Invalid input: expected int" }]
  }
}

Trate o codigo no seu código e mostre a mensagem só para depuração: o texto pode mudar.

Códigos

Código	HTTP	Quando
`requisicao_invalida`	400	Corpo inválido. O campo detalhes lista cada campo com problema.
`json_invalido`	400	O corpo não é um JSON válido.
`idempotency_key_obrigatoria`	400	Falta o header Idempotency-Key.
`nao_autorizado`	401	Chave ausente, inválida ou revogada.
`plataforma_bloqueada`	403	Plataforma reprovada ou suspensa.
`plataforma_nao_aprovada`	403	Chave de produção antes da aprovação.
`cobranca_nao_encontrada`	404	A cobrança não existe nesta conta.
`recebedor_nao_encontrado`	404	O recebedor não existe nesta conta.
`plataforma_ja_cadastrada`	409	Já existe credenciamento para este documento.
`idempotencia_conflito`	422	Idempotency-Key reutilizada com outro corpo.
`split_invalido`	422	Soma acima do valor, recebedor repetido ou regra ambígua.
`split_excede_limite_provedor`	422	Mais recebedores do que o provedor aceita por cobrança.
`recebedor_nao_aprovado`	422	Recebedor ainda sem KYC aprovado.
`recebimento_nao_configurado`	409	A conta de recebimento da plataforma ainda não foi cadastrada (PUT /v1/plataforma/recebimento).
`sem_gateway_disponivel`	422	Nenhum gateway pode processar agora: a mensagem diz o que falta (KYC de quem) em cada um.
`split_sem_espaco_para_tarifa`	422	O split deixa para a plataforma menos que a tarifa do Qorvie Pay.
`recebedor_dados_insuficientes`	422	O provedor exige dados cadastrais que não foram enviados.
`estorno_invalido`	422	O status atual da cobrança não permite estorno.
`chave_publica_invalida`	401	Chave pública ausente ou inválida.
`origem_nao_permitida`	403	A tokenização só é aceita a partir dos campos de cartão hospedados.
`somente_sandbox`	403	Ação que só existe com chave de teste.
`checkout_nao_encontrado`	404	O link de pagamento não existe nesta conta.
`pagamento_em_andamento`	409	Já há um Pix aguardando pagamento neste link.
`checkout_cancelado`	409	O link de pagamento foi cancelado.
`checkout_expirado`	410	O link de pagamento expirou.
`token_invalido`	422	Token de cartão inválido, expirado ou já usado.
`cartao_numero_invalido`	422	Número de cartão inválido. Também: cartao_vencido, cartao_cvv_invalido, cartao_validade_invalida.
`metodo_indisponivel`	422	O meio de pagamento não está habilitado neste link.
`parcelas_invalidas`	422	Mais parcelas do que o link permite.
`cliente_obrigatorio`	422	Cartão exige nome, documento e e-mail do titular.
`origem_invalida`	422	Domínio inválido na lista de domínios permitidos.
`muitas_tentativas`	429	Muitas tentativas de pagamento neste link.
`muitas_requisicoes`	429	Limite de tentativas por endereço. Aguarde alguns minutos.
`tokenizacao_pelo_provedor`	501	Em produção a tokenização é feita pelo SDK do provedor.
`url_invalida`	422	URL de webhook inválida: precisa ser https e pública (rede interna e localhost são recusados).
`limite_de_webhooks`	422	No máximo 5 endpoints de webhook por ambiente.
`webhook_nao_encontrado`	404	O endpoint de webhook não existe nesta conta.
`entrega_nao_encontrada`	404	A entrega de webhook não existe nesta conta.
`provedor_indisponivel`	502	O provedor de pagamento não respondeu. Tente de novo com a mesma Idempotency-Key.

Repetir com segurança

Em 502 ou em falha de rede, repita a requisição com a mesma Idempotency-Key. Se a cobrança chegou a ser criada, você recebe a mesma resposta e não cobra duas vezes.