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	Payload inválido, parâmetros inválidos, data em formato incorreto, CPF/telefone inválido, situação inválida ou benefício inexistente	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	Colaborador, lote ou recurso solicitado não encontrado	Conferir IDs usados na URL
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

Exemplos

Token revogado:

{
  "error": "token_revoked"
}

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
400 ao criar ou atualizar benefício	name, coparticipation_percentage, items, product_id retornado por Listar produtos e monthly_amount
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

Retry

Use retry apenas para falhas temporárias, como 429, 500 e 502. Aplique backoff exponencial e limite de tentativas.

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

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 ou batch_id envolvidos, quando aplicável.
• Payload com dados pessoais mascarados.
• Código HTTP e corpo de erro retornado.

Nunca envie o API token completo.