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

{% 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

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`:

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

{% 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.