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.

A URL de base de todos os endpoints é: https://web.smsfunnel.com.br/api/parceiros/v1

---

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."
            ]
        }
    }
}

O campo details é omitido quando não há informações adicionais. Em erros de validação, ele traz um objeto onde cada chave é o campo inválido e o valor é a lista de mensagens correspondentes.

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	Créditos de SMS insuficientes para concluir a operação.
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	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.
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.

Falhas de autenticação no nível de acesso retornam respostas mais simples, fora do envelope padrão: header ausente/malformado → 401 com {"status":"Authorization header is missing or malformed"}; Chave de API inválida, expirada ou sem permissão → 403 com o corpo Forbidden.

---

Rate Limit

Todas as requisições estão sujeitas a um limite de 60 requisições por minuto, contabilizado por Chave de API (não por IP).

Ao exceder o limite, a resposta será 429 Too Many Requests:

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests. Retry after 30 seconds."
    }
}

Headers de controle

As respostas acompanham headers que informam o estado atual do seu limite:

Header	Descrição
Retry-After	Segundos a aguardar antes de tentar novamente (presente no 429).
X-RateLimit-Limit	Total de requisições permitidas na janela (60).
X-RateLimit-Remaining	Quantidade de requisições ainda disponíveis na janela atual.

Boa prática: ao receber um 429, aguarde o tempo indicado em Retry-After antes de repetir a requisição. Para envios em massa, prefira agrupar destinatários em uma única chamada (até 5.000 mensagens por requisição) em vez de múltiplas chamadas pequenas.

Dúvidas?

Em caso de dúvidas, entre em contato com nosso suporte.