Skip to main content

Códigos de Status HTTP

A API Carteira NeverMiss usa códigos de status HTTP padrão para indicar sucesso ou falha:

2xx - Sucesso

A requisição foi bem-sucedida

4xx - Erro do Cliente

Erro causado por dados inválidos ou ação não permitida

5xx - Erro do Servidor

Erro interno do servidor

Códigos de Sucesso

Códigos de Erro do Cliente

400 - Bad Request

Dados inválidos ou campos obrigatórios faltando. Exemplo de resposta:
Causas comuns:
  • Valor do pagamento inválido ou negativo
  • Descrição faltando ao criar pagamento
  • Chave PIX inválida para o tipo especificado
  • JSON malformado no body da requisição
Solução:
  • Valide os dados antes de enviar
  • Verifique se todos os campos obrigatórios estão presentes
  • Confirme que os tipos de dados estão corretos

401 - Unauthorized

Autenticação falhou ou API Key inválida. Exemplo de resposta:
Causas comuns:
  • API Key ausente no header
  • API Key inválida ou revogada
  • Formato do header Authorization incorreto
Solução:
  • Verifique se o header Authorization: Bearer SUA_API_KEY está presente
  • Confirme que a API Key está correta
  • Entre em contato com o suporte se a chave foi revogada

403 - Forbidden

Ação não permitida no estado atual. Exemplo de resposta:
Causas comuns:
  • Tentar saque manual com saque automático ativado
  • Tentar atualizar configuração bloqueada
  • Operação não permitida para seu tipo de conta
Solução:
  • Desative o saque automático antes de sacar manualmente
  • Verifique os pré-requisitos da operação
  • Consulte a documentação do endpoint específico

404 - Not Found

Recurso não encontrado. Exemplo de resposta:
Causas comuns:
  • Transaction ID (txid) inválido ou inexistente
  • Tentar acessar transação de outro usuário
  • Endpoint incorreto
Solução:
  • Verifique se o txid está correto
  • Confirme que a transação pertence à sua conta
  • Verifique a URL do endpoint

409 - Conflict

Conflito com o estado atual do recurso. Exemplo de resposta:
Causas comuns:
  • Tentar criar segundo saque com um já pendente
  • Tentar reembolsar pagamento já reembolsado
  • Operação duplicada
Solução:
  • Aguarde o saque pendente ser processado
  • Verifique o status atual antes de fazer a operação
  • Implemente idempotência no seu código

429 - Too Many Requests

Rate limit excedido. Exemplo de resposta:
Causas comuns:
  • Mais de 60 requisições por minuto
  • Múltiplas chamadas ao mesmo endpoint em curto período
  • Polling muito frequente
Solução:
  • Implemente backoff exponencial
  • Use webhooks em vez de polling constante
  • Respeite o campo retryAfter
  • Veja a página de Rate Limits para mais detalhes

Códigos de Erro do Servidor

500 - Internal Server Error

Erro interno do servidor. Exemplo de resposta:
Causas:
  • Erro inesperado no processamento
  • Problema temporário na infraestrutura
  • Falha em serviço externo (Banco Central, etc.)
Solução:
  • Tente novamente após alguns segundos
  • Se persistir, entre em contato com o suporte
  • Verifique a página de status (se disponível)

Estrutura de Resposta de Erro

Todos os erros seguem uma estrutura consistente:

Tratamento de Erros

Boas Práticas

Erros Específicos por Endpoint

POST /v1/payment/create

GET /v1/payment/status/:txid

POST /v1/withdraw

POST /v1/withdraw/cancel

POST /v1/pix/validate

POST /v1/refund

GET /v1/balance

Suporte

Se você encontrar erros não documentados ou precisar de ajuda: Ao reportar um erro, inclua:
  • Request ID (header X-Request-ID da resposta)
  • Código de status HTTP
  • Mensagem de erro completa
  • Timestamp do erro
  • Endpoint que causou o erro