> For the complete documentation index, see [llms.txt](https://docs.smsfunnel.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smsfunnel.com.br/api/parceiros/referencia.md).

# 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.

{% hint style="success" %}
**A URL de base de todos os endpoints é**: <https://web.smsfunnel.com.br/api/parceiros/v1>
{% endhint %}

***

#### 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.

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

{% hint style="info" %}
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.
{% endhint %}

**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.                                                                                                         |

{% hint style="warning" %}
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`.
{% endhint %}

***

#### 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-Of` tê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`:

```json5
{
    "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.                         |
| `X-RateLimit-Remaining` | Quantidade de requisições ainda disponíveis na janela atual.       |

{% hint style="warning" %}
**`X-RateLimit-*` refletem o teto por chave.** Como há dois limites (por conta e por chave), os headers `X-RateLimit-Limit` e `X-RateLimit-Remaining` mostram o **teto por chave (600/min)**, não o limite da conta. Você pode receber `429` com `X-RateLimit-Remaining` ainda alto. Use o `Retry-After` do `429` como referência.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

**Dúvidas?**

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