Erros

A API retorna códigos HTTP para indicar falhas de validação, autenticação, autorização ou indisponibilidade temporária.

Códigos esperados

HTTP	Quando acontece	Ação recomendada
400	Identificador ou dado de entrada inválido, como CPF, telefone, situação ou data em formato incorreto	Corrigir os dados enviados
401	Token ausente, inválido, expirado ou revogado	Conferir header Authorization ou solicitar novo token
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
404	Produto, benefício, colaborador, lote ou outro recurso solicitado não encontrado	Conferir os IDs usados
409	Conflito específico, como tentativa de cancelar uma cobrança já paga ou external_reference já utilizado com dados divergentes ao criar distribuição (code EXTERNAL_REFERENCE_CONFLICT)	Consultar o recurso relacionado antes da próxima ação; em distribuições, localizar a existente pela listagem ou usar um novo external_reference
422	Estado incompatível, limite operacional, regra de negócio ou método não suportado	Consultar o recurso e corrigir a condição indicada
429	Rate limit	Reduzir taxa de chamadas e aplicar retry com backoff
500	Erro interno temporário	Tentar novamente e acionar suporte se persistir
502	Indisponibilidade temporária de serviço intermediário	Tentar novamente com backoff
503	Dependência temporariamente indisponível	Tentar novamente com backoff
504	Tempo limite excedido	Consultar o estado do recurso antes de tentar novamente

Exemplos

Falhas 401 usam um envelope estruturado com success, message, code, error e data. O conteúdo de data varia conforme a causa; use o status HTTP e o code retornado, sem depender do texto da mensagem.

Falhas 409 de idempotência ao criar distribuição trazem o code estável no topo do envelope (pode incluir trace_id):

{
  "success": "error",
  "message": "External reference already used with different data",
  "code": "EXTERNAL_REFERENCE_CONFLICT",
  "data": {
    "code": "EXTERNAL_REFERENCE_CONFLICT"
  }
}

Resposta de sucesso esperada para comparação:

{
  "success": "success",
  "data": {}
}

Diagnóstico rápido

Sintoma	Verifique
401 em todas as rotas	Token copiado corretamente, prefixo Bearer, token do ambiente certo
403 em chamadas autenticadas	Token ativo e autorizado para o recurso solicitado
400 ao criar ou atualizar colaborador	Formato de datas YYYY-MM-DD, CPF, telefone, benefit_id obtido pela API e situation obtida pela rota de situações
404 ao criar ou atualizar benefício	product_id retornado por Listar produtos
422 ao criar ou atualizar benefício	name, items, produtos repetidos e disponibilidade do benefício
404 ao buscar colaborador	employee_id retornado pela API
400 no commit de lote	batch_id e benefit_id obtido pelas rotas de benefícios
403 em depósitos ou distribuições	Token ativo e autorizado para o recurso solicitado
400 ao criar distribuição	external_reference com mais de 128 caracteres ou com caracteres de controle
409 ao criar distribuição	external_reference já usado pela empresa com type ou benefit_convention_ids diferentes; repita com exatamente os mesmos dados para receber a distribuição existente ou use outro external_reference
404 ao consultar depósito	transaction_id retornado pela API e ambiente correto
403 ao consultar distribuição	distribution_id retornado pela API, ambiente e token corretos
422 ao editar ou regenerar distribuição	Estado draft para edição; estado expired para regeneração
422 ao finalizar	Estado draft, método de pagamento aceito, saldo e valores em centavos

Retry

Use retry apenas para falhas temporárias, como 429, 500, 502, 503 e 504. Aplique backoff exponencial, limite de tentativas e, em 429, respeite o header Retry-After quando ele estiver presente.

Não faça retry automático infinito para 400, 401, 403, 404, 409 ou 422; esses códigos normalmente exigem correção de dados, estado ou configuração.

Depois de timeout ou qualquer 5xx em uma mutação financeira, consulte o depósito ou a distribuição antes de repetir a chamada. Na criação de distribuições, envie external_reference para que a repetição devolva a distribuição já criada em vez de duplicá-la.

Dados para suporte

Ao acionar suporte, envie:

• Endpoint chamado, sem token.
• Método HTTP.
• Horário aproximado da chamada com fuso horário.
• employee_id, benefit_id, batch_id, transaction_id, distribution_id ou external_reference envolvidos, quando aplicável.
• Payload com dados pessoais mascarados.
• Código HTTP e corpo de erro retornado.

Nunca envie o API token completo.