Erros e códigos - V4 Pay

Esta página é para o desenvolvedor que recebeu um erro e quer resolver rápido.

O formato

Erro vem em error, como objeto. Erros de negócio trazem codigo, um identificador estável para o seu código tratar — a message é para gente, pode mudar de texto:

{ "error": { "message": "…", "codigo": "VALOR_MINIMO", "valor_minimo": 5 } }

Duas exceções para conhecer:

Autenticação: quando a credencial falha (401), error é uma string, não um objeto: { "error": "Token JWT ou chave de API ausente" }. Trate os dois formatos.
Erro inesperado (500): a resposta traz um id de correlação ({ "error": { "message": "Erro interno… informe o código a1b2c3d4.", "id": "a1b2c3d4" } }). Informe esse código ao suporte — ele liga a sua chamada ao log exato.

Os códigos

`codigo`	Status	Onde acontece	O que fazer
`PRODUCAO_NAO_LIBERADA`	409 (403 em chave live)	qualquer operação de produção antes da aprovação	complete a aprovação de produção; o bloco `producao` da resposta diz em que pé está
`CADASTRO_INCOMPLETO`	400	`POST /producao/solicitar`	complete os campos de `faltando` e envie os documentos de `documentos_faltando`
`STATUS_NAO_PERMITE`	409	mexer em documentos com o cadastro em análise/aprovado; aprovar ou recusar quem não está `pending`	espere a análise terminar (ou confira o status atual em `GET /producao`)
`SOMENTE_PAINEL`	403	chave de API tentando enviar documento de produção, ou criar/editar/revogar chave de API	use a sessão do painel: credencial não cria credencial, e documento não viaja por chave
`SOMENTE_TITULAR`	403	membro de loja compartilhada mexendo no cadastro de produção, nas chaves de API, nos webhooks ou na conta de recebimento do dono	só o titular cuida de credencial e de cadastro da própria loja
`SOMENTE_ADMIN`	403	rotas da equipe V4 Pay (aprovações, edição do Roadmap)	não é para integração — se você deveria ser admin, fale com a equipe
`SOMENTE_AUTOR_OU_ADMIN`	403	apagar comentário do Roadmap que não é seu	só o autor (ou a equipe) apaga
`EXPIRACAO_INVALIDA`	400	`POST /pix` e `POST /charges` com `expires_at` no passado ou que não é uma data	use uma data futura, em ISO 8601 com fuso (há 1 minuto de tolerância para relógio)
`VALOR_MINIMO`	400	emitir cobrança ou criar link abaixo de R$ 5,00 — inclusive quando um cupom derruba o total	cobre pelo menos R$ 5,00; a resposta traz `valor_minimo`
`LINK_INDISPONIVEL`	409	checkout público de um link cujo dono não pode emitir	mensagem neutra para o pagador; o dono vê o motivo real na conta dele
`REPASSE_MANUAL`	409	`POST /withdrawals` no modo conta única	o saque está suspenso; o repasse é manual — veja Modo de recebimento
`MUITAS_REFERENCIAS`	409	excluir cupom, produto ou assinatura com mais de 500 referências	desative (`is_active`/`active: false` ou `status: canceled`) em vez de excluir — o histórico fica íntegro
`SKU_DUPLICADO`	409	criar/editar produto com `sku` que você já usa	troque o `sku` ou edite o produto existente
`CNPJ_JA_CADASTRADO`	409	`POST /receiving-account` com CNPJ que já tem subconta	a conta de recebimento desse CNPJ já existe — confira `GET /receiving-account`
`SUBCONTA_INEXISTENTE`	409	emitir em produção, no modo subconta, sem ter cadastrado a empresa	complete o cadastro em `POST /receiving-account`
`SUBCONTA_NAO_APROVADA`	409	emitir com a subconta ainda em análise no motor de pagamentos	veja o bloco `aprovacao` da resposta e o `link_documentos` de `GET /receiving-account`
`PROVEDOR_NAO_CONFIGURADO`	500	o servidor está sem as credenciais do motor de pagamentos	não é erro seu — avise o suporte

400 sem codigo é validação comum (campo faltando, documento com dígito verificador errado, CEP inválido…) — a message diz exatamente o quê.