For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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.


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:

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.

Last updated