API — Códigos de erro e troubleshooting

Referência dos códigos HTTP retornados pela API, formato dos erros (incluindo o objeto errors do 422) e causas comuns: token inválido, addon/licença, rate limit e isolamento por tenant.

API — Códigos de erro e troubleshooting

Códigos HTTP

CódigoSignificadoCausa típica
200OKSucesso (leitura/atualização)
201CreatedRecurso criado
400Bad RequestRequisição inválida (ex: mensagem sem conteúdo, falha no provedor de envio)
401UnauthenticatedToken ausente, inválido ou expirado
403ForbiddenSem permissão: licença sem API, addon api_access inativo, ou tenant ausente
404Not FoundRecurso inexistente OU pertencente a outro tenant
422Validation ErrorDados inválidos (detalhes em errors) ou regra de negócio (ex: fatura não aceita pagamento)
429Too Many RequestsRate limit excedido (60/min por token)
500Server ErrorErro interno

Formato do erro

{
  "error": "Contact not found.",
  "errors": {                 // presente apenas em 422
    "name": ["O campo name é obrigatório."],
    "email": ["O campo email deve ser um endereço de e-mail válido."]
  }
}

Em validação (422) o Laravel retorna o objeto errors com a lista de mensagens por campo. Em demais erros, há a chave error com a descrição.

Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.
Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.

Mensagens de 403 e o que fazer

  • "API access is not available on this license." — o plano do tenant não inclui API. É preciso um plano com API habilitada.
  • "API Access addon is not active. Please activate it in Settings → Addons." — ative o addon api_access na Loja de Aplicativos.
  • "Tenant not found." — o usuário do token não está vinculado a um tenant.

Rate limit (429)

Limite de 60 requisições/minuto por token. A resposta inclui X-RateLimit-Limit, X-RateLimit-Remaining e, no 429, Retry-After: 60. Implemente retry com backoff e respeite o Retry-After. Distribua a carga ou use mais de um token quando necessário.

Checklist de diagnóstico

  1. 401: confira o header Authorization: Bearer ... e se o token não foi revogado.
  2. 403: confira licença e o addon api_access.
  3. 404 inesperado: o ID provavelmente é de outro tenant — a API isola dados por tenant.
  4. 422: leia errors; cheque obrigatórios e os in: (enums) de cada campo. Atenção a discount_type: faturas usam percent, propostas usam percentage.
  5. 400 ao enviar mensagem: canal de WhatsApp pode estar desconectado.
  6. Sempre envie Accept: application/json para receber erros em JSON.
api erros troubleshooting http status code integração

Este artigo foi útil?

Artigos Relacionados