Sempre que uma chamada não puder ser processada corretamente, a API retornará um código de erro acompanhado de uma mensagem explicando o motivo da falha.

Como interpretar uma resposta de erro

Exemplo:

{
  "message": "Unauthorized"
}

Nesse caso:

• A requisição foi recebida pela API;
• O processamento foi interrompido;
• A mensagem informa o motivo da falha.

Códigos de Status HTTP

200 — Sucesso

Indica que a operação foi executada corretamente.

Exemplo:

200 OK

201 — Recurso Criado

Indica que um novo recurso foi criado com sucesso.

Exemplo:

201 Created

Comum em operações como:

• Criar contato
• Criar oportunidade
• Criar registro CRM

400 — Bad Request

A requisição enviada possui dados inválidos ou incompletos.

Exemplo:

{
  "message": "Campo obrigatório não informado"
}

Causas comuns:

• Campo obrigatório ausente;
• Formato inválido;
• Tipo de dado incorreto;
• JSON mal formatado.

Como corrigir

Verifique:

• Campos obrigatórios;
• Estrutura do JSON;
• Tipos de dados enviados.

401 — Unauthorized

A autenticação não foi realizada corretamente.

Exemplo:

{
  "message": "Unauthorized"
}

Causas comuns:

• Token inválido;
• Token revogado;
• Token ausente;
• Header Authorization não enviado.

Como corrigir

Verifique se o header foi enviado corretamente:

Authorization: Bearer pn_xxxxxxxxxxxxx

403 — Forbidden

A autenticação foi realizada, mas a conta não possui permissão para executar a ação.

Exemplo:

{
  "message": "Forbidden"
}

Causas comuns:

• Falta de permissão;
• Recurso restrito;
• Perfil sem acesso à funcionalidade.

404 — Not Found

O recurso solicitado não foi encontrado.

Exemplo:

{
  "message": "Not Found"
}

Causas comuns:

• ID inexistente;
• Registro removido;
• Endpoint incorreto.

Exemplo

Contato solicitado não existe

ou

Sessão informada não encontrada

409 — Conflict

Ocorre quando a operação gera conflito com dados existentes.

Exemplo:

{
  "message": "Conflict"
}

Possíveis causas:

• Registro duplicado;
• Estado incompatível para execução;
• Violação de regra de negócio.

429 — Too Many Requests

O limite de requisições foi excedido.

Exemplo:

{
  "message": "Too Many Requests"
}

Como corrigir

Reduza a frequência das chamadas.

Recomendamos implementar retry com backoff exponencial.

Exemplo:

1ª tentativa
↓
Aguardar 2 segundos

2ª tentativa
↓
Aguardar 5 segundos

3ª tentativa
↓
Aguardar 10 segundos

Consulte também:

👉 Rate Limiting

500 — Internal Server Error

Erro interno durante o processamento da requisição.

Exemplo:

{
  "message": "Internal Server Error"
}

Como agir

• Aguarde alguns segundos;
• Realize uma nova tentativa;
• Verifique logs da integração;
• Entre em contato com o suporte caso o problema persista.

Boas Práticas

Sempre valide respostas

Não assuma que todas as chamadas retornarão sucesso.

Exemplo:

if (response.status !== 200) {
  // tratar erro
}

Implemente logs

Registre:

• Endpoint chamado;
• Payload enviado;
• Status HTTP;
• Mensagem retornada.

Isso facilita diagnósticos futuros.

Trate timeouts

Conexões de rede podem falhar.

Implemente mecanismos de:

• Retry;
• Timeout;
• Monitoramento.

Trate erros 429 corretamente

Nunca execute novas chamadas imediatamente após receber:

429 Too Many Requests

Utilize intervalos progressivos entre as tentativas.

Solução de Problemas

Estou recebendo 401

Verifique:

• Token válido;
• Header Authorization;
• Prefixo Bearer.

Estou recebendo 404

Verifique:

• URL utilizada;
• ID informado;
• Existência do recurso.

Estou recebendo 429

Verifique:

• Volume de chamadas;
• Loops automáticos;
• Configuração do Rate Limit.

Estou recebendo 500

Verifique:

• Logs da aplicação;
• Disponibilidade da API;
• Dados enviados.

Caso o problema persista, entre em contato com o suporte.