Skip to main content

Erros de Autenticação

401 Unauthorized

Problema: A requisição não inclui o header Authorization.Solução: Adicione o header com sua chave de API:
Problema: A chave está sendo enviada sem o prefixo Bearer.Errado:
Correto:
Problema: A chave não existe ou foi revogada.Solução:
  1. Acesse o Dashboard
  2. Vá para ConfiguraçõesDesenvolvedores
  3. Verifique se a chave está ativa ou crie uma nova

403 Forbidden

Problema: Sua chave de API não tem permissão para acessar este recurso.Solução: Verifique as permissões da chave no Dashboard ou crie uma nova chave com as permissões necessárias.
Problema: Você está tentando acessar ou modificar um produto que não pertence à sua conta.Solução: Verifique se o ID ou UUID do produto está correto e pertence à sua conta.

Erros de Validação

400 Bad Request

Problema: O preço do produto é menor que R$ 5,00.Solução: Defina um valor de pelo menos 5.00:
Problema: Campos obrigatórios não foram enviados.Campos obrigatórios para criar produto:
  • name (string)
  • description (string)
  • value (number)
  • pix (boolean)
  • creditCard (boolean)
  • boleto (boolean)
  • installments (number, 1-12)
Problema: O número de parcelas está fora do intervalo permitido.Solução: Use um valor entre 1 e 12:
Problema: Pelo menos um método de pagamento deve estar ativo.Solução: Habilite pelo menos um:

Erros de Limite

429 Too Many Requests

Problema: Você excedeu o limite de 100 requisições por minuto.Solução: Implemente retry com backoff exponencial:

Erros de Recurso

404 Not Found

Problema: O ID ou UUID do produto não existe.Soluções:
  1. Verifique se o ID/UUID está correto
  2. O produto pode ter sido excluído
  3. Liste seus produtos para confirmar os IDs disponíveis

Problemas com Webhooks

Webhook não está sendo recebido

Problema: Seu servidor não está acessível pela internet.Soluções:
  1. Verifique se o endpoint está online
  2. Use HTTPS (HTTP não é suportado)
  3. Para testes locais, use ngrok
Problema: Seu endpoint demora mais de 5 segundos para responder.Solução: Responda imediatamente com 200 e processe assincronamente:
Problema: Seu endpoint retorna erro (4xx ou 5xx).Solução: Verifique os logs do servidor e corrija os erros. A Garu tentará reenviar até 5 vezes.

Assinatura inválida

Problema: O segredo usado para validar não corresponde.Solução:
  1. Acesse ConfiguraçõesWebhooks no Dashboard
  2. Copie o segredo correto
  3. Atualize a variável de ambiente WEBHOOK_SECRET
Problema: O corpo da requisição foi alterado antes da validação.Solução: Use o payload raw, não o parseado:

Problemas com Pagamento

Problema: O produto foi excluído (soft delete).Solução: Reative o produto ou crie um novo.
Problema: O UUID na URL está errado.Solução: Verifique o UUID correto listando seus produtos:

Checklist de Integração

Use este checklist antes de ir para produção:
1

Autenticação

  • Chave de API armazenada em variável de ambiente
  • Usando sk_test_ em desenvolvimento
  • Testou com sk_live_ em staging
2

Criação de Produtos

  • Todos os campos obrigatórios preenchidos
  • Preço mínimo de R$ 5,00
  • Pelo menos um método de pagamento ativo
  • UUID sendo salvo no banco de dados
3

Webhooks

  • Endpoint configurado com HTTPS
  • Validação de assinatura implementada
  • Resposta rápida (< 5 segundos)
  • Processamento assíncrono para tarefas longas
  • Idempotência para evitar duplicações
4

Tratamento de Erros

  • Retry com backoff para erros 429
  • Logs para debugging
  • Alertas para erros críticos

Precisa de Ajuda?

Se você não conseguiu resolver seu problema:
  1. Verifique a especificação OpenAPI
  2. Acesse o suporte no Dashboard
  3. Envie um email para contato@garu.com.br

Suporte

Entre em contato com nossa equipe de suporte técnico