Referência
Esta seção reúne os padrões comuns a todos os endpoints da API de parceiros: o formato de resposta de erros e os limites de requisição.
Envelope de Erro
Sempre que uma requisição falha, a resposta segue um formato padronizado, com a chave error contendo o código, a mensagem e, quando aplicável, os detalhes do erro.
{
"error": {
"code": "VALIDATION_ERROR", // Código do erro (identificador estável)
"message": "The given data was invalid.", // Descrição legível do erro
"details": { // Opcional: presente apenas em alguns erros (ex.: validação)
"name": [
"Field `name` is required."
]
}
}
}Códigos de Erro
HTTP
code
Descrição
401 Unauthorized
UNAUTHORIZED
Não foi possível identificar o parceiro a partir da Chave de API.
402 Payment Required
INSUFFICIENT_CREDITS
Saldo insuficiente para concluir a operação. No envio de SMS, só para contas no pacote de créditos — na Carteira o saldo é conferido no processamento (veja Saldo e Carteira).
403 Forbidden
OUTSIDE_SEND_WINDOW
Envio ou agendamento de SMS fora da janela de 07:00 às 22:00 (horário de Brasília).
403 Forbidden
ON_BEHALF_NOT_ALLOWED
Header X-On-Behalf-Of enviado por uma chave que não é de conta agência.
404 Not Found
NOT_FOUND
O recurso solicitado não foi encontrado ou não pertence à sua conta.
409 Conflict
INVALID_STATUS_TRANSITION
A operação não é permitida no status atual do recurso (ex.: cancelar broadcast enviado).
409 Conflict
BROADCAST_INTERVAL_NOT_RESPECTED
O disparo não respeita o intervalo mínimo entre broadcasts exigido pela sua conta.
409 Conflict
INVALID_SEQUENCE_TYPE
Endpoint de ligações chamado para uma sequência que não é de voz.
409 Conflict
AUDIO_IN_USE
O áudio está em uso e não pode ser removido.
409 Conflict
CONCURRENT_REQUEST
Já existe uma requisição em processamento com o mesmo Idempotency-Key.
409 Conflict
LIST_HAS_DEPENDENT_CAMPAIGNS
Tentativa de remover uma lista que ainda possui campanhas vinculadas.
422 Unprocessable Entity
VALIDATION_ERROR
Algum campo do corpo da requisição é inválido.
422 Unprocessable Entity
AUDIO_NOT_READY
O áudio ainda não terminou de ser processado.
422 Unprocessable Entity
EMPTY_LEAD_LIST
A lista informada no disparo de ligações não tem leads.
422 Unprocessable Entity
INVALID_CURSOR
Cursor de paginação inválido.
422 Unprocessable Entity
PERIOD_TOO_LONG
Período das métricas de ligação maior que 366 dias.
429 Too Many Requests
RATE_LIMIT_EXCEEDED
Limite de requisições por minuto excedido.
500 Internal Server Error
INTERNAL_ERROR
Ocorreu um erro interno ao processar a requisição.
502 Bad Gateway
SHORTENER_UNAVAILABLE
Falha temporária ao gerar o link curto de "Meu Link". Tente novamente.
Rate Limit
As requisições estão sujeitas a dois limites, contabilizados por minuto:
Por conta efetiva: 60 requisições por minuto (limite padrão). Agências operando contas filhas com
X-On-Behalf-Oftêm um limite separado para cada filha (veja Agências).Por Chave de API: 600 requisições por minuto, como teto global da chave.
Os endpoints legados /call4u/* têm limite próprio, contabilizado por endereço IP.
Ao exceder o limite, a resposta será 429 Too Many Requests:
Headers de controle
As respostas acompanham headers que informam o estado atual do seu limite:
Retry-After
Segundos a aguardar antes de tentar novamente (presente no 429).
X-RateLimit-Limit
Total de requisições permitidas na janela.
X-RateLimit-Remaining
Quantidade de requisições ainda disponíveis na janela atual.
Dúvidas?
Em caso de dúvidas, entre em contato com nosso suporte.
Last updated