# Cabeçalhos

Fonte: https://apiwpp.com/docs/referencia/cabecalhos
Seção: Referência
Atualizado em: 2026-09-29

Os cabeçalhos HTTP da API: os que você envia (a chave e o Content-Type), os que as respostas trazem e os que chegam em cada entrega de webhook.

A API usa poucos cabeçalhos próprios. Na requisição, você envia a chave de API e, quando há corpo, o `Content-Type`. Nas respostas, os cabeçalhos dizem quanto esperar antes de repetir e quanto da cota já foi usado. Nas entregas de webhook, eles trazem o token e a assinatura do projeto. Os nomes não diferenciam maiúsculas de minúsculas.

## Na requisição

| Cabeçalho | Quando | Valor |
| --- | --- | --- |
| `Authorization` | Em toda operação, exceto [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia) | `Bearer wag_live_…`: a chave de API |
| `X-Api-Key` | No lugar de `Authorization`, se preferir | `wag_live_…`: a mesma chave, sem o `Bearer` |
| `Content-Type` | Só nas requisições com corpo | `application/json` |

### A chave de API

A chave vai em **um** dos dois cabeçalhos; os dois valem para todas as operações. Ela tem o formato `wag_live_<prefixo de 8 caracteres>_<segredo de 43 caracteres>` e é mostrada uma única vez, quando é criada. Veja [Autenticação](https://apiwpp.com/docs/autenticacao).

**Authorization**

```bash
curl -s https://api.apiwpp.com/me \
  -H "Authorization: Bearer $API_KEY"
```

**X-Api-Key**

```bash
curl -s https://api.apiwpp.com/me \
  -H "X-Api-Key: $API_KEY"
```

- Sem nenhum dos dois, ou com uma chave desconhecida, revogada, expirada ou de um projeto desativado, a resposta é `401` com `{ "error": "Unauthorized" }`.
- Se você enviar os dois cabeçalhos, eles precisam trazer a mesma chave. Chaves diferentes respondem `401`.
- Cada chave errada conta para o limite de falhas de autenticação do IP: 20 em 5 minutos, por padrão, e depois `429` com `Retry-After`. A chave certa continua funcionando nesse período.
- [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia) não pede chave: a própria URL, assinada e com validade, é a credencial.

### O corpo em JSON

As operações com corpo recebem JSON. Envie `Content-Type: application/json` **só** quando houver corpo:

| O que você envia | Resposta |
| --- | --- |
| `Content-Type: application/json` e um JSON válido | A operação é atendida |
| `Content-Type: application/json` e corpo vazio (por exemplo, num `POST` de desconectar, que não tem corpo) | `400` com `code: FST_ERR_CTP_EMPTY_JSON_BODY` |
| `Content-Type: application/json` e um corpo que não é JSON | `400` com `code: FST_ERR_CTP_INVALID_JSON_BODY` |
| Um corpo em outro formato, como `application/x-www-form-urlencoded` | `415` com `code: FST_ERR_CTP_INVALID_MEDIA_TYPE` |
| Um corpo com mais de 1 MiB | `413` com `code: FST_ERR_CTP_BODY_TOO_LARGE` |

**Operação sem corpo: sem Content-Type**

```bash
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/disconnect \
  -H "Authorization: Bearer $API_KEY"
```

> **Não existe Idempotency-Key**
>
> A API não lê um cabeçalho `Idempotency-Key`. A idempotência do envio é o campo `clientRef` do corpo de [`POST /connections/{id}/send`](https://apiwpp.com/docs/api/mensagens/enviar-mensagem): a repetição com o mesmo `clientRef` responde `200` com `duplicate: true` e o job original. Veja [Idempotência](https://apiwpp.com/docs/guias/idempotencia).

## Na resposta

| Cabeçalho | Em quais respostas | Valor |
| --- | --- | --- |
| `Retry-After` | `429` dos limites que passam sozinhos; `503` de instância mudando; `409 not_pairing` quando os QR codes terminam cedo demais | Segundos até valer a pena repetir |
| `X-Usage-Percent` | `429` da cota do plano, só no envio | O uso da cota diária ou mensal, em porcentagem inteira |
| `X-Usage-Warning` | Envios aceitos (`202`) a partir de 80% da cota | `Approaching limit: 85% used` |
| `X-RateLimit-Limit` | Toda resposta contada pelo limite de requisições | As requisições permitidas por janela: 600, por padrão |
| `X-RateLimit-Remaining` | Idem | Quantas ainda cabem na janela atual |
| `X-RateLimit-Reset` | Idem | Segundos até a janela recomeçar |
| `Content-Type` | Todas | `application/json`; em [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia), o tipo do arquivo |
| `Cache-Control` | [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia) | `private, max-age=…`: até 1 hora, e nunca além da validade da URL |

### Retry-After

Quando a resposta traz `Retry-After`, espere esse número de segundos e repita a mesma requisição. Ele aparece em:

| Status | Quando |
| --- | --- |
| `429` | Requisições demais do mesmo IP (600 por minuto, por padrão) |
| `429` | Falhas de autenticação demais do mesmo IP (20 em 5 minutos, por padrão) |
| `429` `new_recipient_cap_reached` | O número alcançou o limite de destinatários novos das últimas 24 horas, no [envio](https://apiwpp.com/docs/api/mensagens/enviar-mensagem) |
| `429` `pairing_code_too_soon` | Um [código de pareamento](https://apiwpp.com/docs/api/conexoes/codigo-de-pareamento) pedido cedo demais |
| `429` | Verificações de proxy demais da organização (60 por hora), em [Definir proxy](https://apiwpp.com/docs/api/conexoes/definir-proxy) |
| `503` | A instância do gateway que atende a conexão está mudando ou não responde |
| `409` `not_pairing` | Os QR codes do pareamento terminam cedo demais para alguém digitar um código |

O `429` da cota do plano **não** traz `Retry-After`: repetir não adianta até a cota renovar ou o plano mudar. Veja [Códigos de erro](https://apiwpp.com/docs/referencia/codigos-de-erro#429-limite-atingido).

### X-Usage-Percent e X-Usage-Warning

Os dois só aparecem em [`POST /connections/{id}/send`](https://apiwpp.com/docs/api/mensagens/enviar-mensagem) e medem a cota de mensagens da organização, somando as já enviadas de todos os projetos dela e as que estão na fila.

- **`X-Usage-Warning`** vem nos envios aceitos (`202`) quando o uso passa de 80% do limite diário ou do mensal, por exemplo `Approaching limit: 85% used`. É o aviso para agir antes do bloqueio.
- **`X-Usage-Percent`** vem no `429` da cota esgotada, com a porcentagem do limite que bloqueou. O bloqueio acontece com 10% de tolerância acima do limite, então o valor passa de 100 (por exemplo, `110`).

Uma repetição com o mesmo `clientRef` de um envio já aceito responde `200` antes da verificação de cota e não traz esses cabeçalhos.

**cURL**

```bash
# -i mostra o status e os cabeçalhos da resposta
curl -si -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777", "message": "Olá!", "clientRef": "pedido-1234"}'
```

**Node.js**

```javascript
// Node.js 18+: fetch nativo
const res = await fetch(`https://api.apiwpp.com/connections/${process.env.CONNECTION_ID}/send`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: '5511988887777', message: 'Olá!', clientRef: 'pedido-1234' }),
})

const warning = res.headers.get('x-usage-warning')
if (warning) console.warn(`Cota de mensagens perto do fim: ${warning}`)

const remaining = Number(res.headers.get('x-ratelimit-remaining'))
if (remaining < 50) console.warn(`Restam ${remaining} requisições nesta janela`)

if (res.status === 429 || res.status === 503) {
  const retryAfter = Number(res.headers.get('retry-after'))
  const usagePercent = res.headers.get('x-usage-percent')
  if (usagePercent) {
    // Cota do plano esgotada: não repita
  } else if (retryAfter > 0) {
    // Espere retryAfter segundos e repita com o mesmo clientRef
  }
}
```

**PHP**

```php
<?php
$ch = curl_init('https://api.apiwpp.com/connections/' . getenv('CONNECTION_ID') . '/send');
$headers = [];
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['to' => '5511988887777', 'message' => 'Olá!', 'clientRef' => 'pedido-1234']),
    // Guarda os cabeçalhos da resposta, com o nome em minúsculas
    CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$headers) {
        $parts = explode(':', $line, 2);
        if (count($parts) === 2) {
            $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
        }
        return strlen($line);
    },
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if (isset($headers['x-usage-warning'])) {
    error_log('Cota de mensagens perto do fim: ' . $headers['x-usage-warning']);
}
if (($status === 429 || $status === 503) && !isset($headers['x-usage-percent'])) {
    $retryAfter = (int) ($headers['retry-after'] ?? 0);
    // Espere $retryAfter segundos e repita com o mesmo clientRef
}
```

**Python**

```python
# pip install requests
import os

import requests

res = requests.post(
    f"https://api.apiwpp.com/connections/{os.environ['CONNECTION_ID']}/send",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"to": "5511988887777", "message": "Olá!", "clientRef": "pedido-1234"},
    timeout=30,
)

# requests trata os nomes dos cabeçalhos sem diferenciar maiúsculas
if "X-Usage-Warning" in res.headers:
    print("Cota de mensagens perto do fim:", res.headers["X-Usage-Warning"])

if res.status_code in (429, 503) and "X-Usage-Percent" not in res.headers:
    retry_after = int(res.headers.get("Retry-After", "0") or 0)
    # Espere retry_after segundos e repita com o mesmo clientRef
```

Resposta `202`

```http
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 41
X-Usage-Warning: Approaching limit: 85% used
```

### X-RateLimit

As respostas contadas pelo limite de requisições trazem `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`. O limite é por **IP de origem**, não por chave: todas as chaves que saem do mesmo IP dividem a mesma janela. Quando ela acaba, a resposta é `429` com `X-RateLimit-Remaining: 0` e `Retry-After`. Veja [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio).

## Nas entregas de webhook

Cada entrega de evento ao `webhookBaseUrl` do projeto é um `POST` com estes cabeçalhos:

| Cabeçalho | Quando | Valor |
| --- | --- | --- |
| `Content-Type` | Sempre | `application/json` |
| `X-Webhook-Token` | Sempre | O `webhookToken` do projeto |
| `X-Sales-Timestamp` | Com um `webhookSecret` no projeto | Segundos unix do momento da tentativa; cada nova tentativa é assinada de novo |
| `X-Sales-Signature` | Com um `webhookSecret` no projeto | `sha256=` + hex(HMAC-SHA256(`webhookSecret`, `timestamp` + `"."` + corpo bruto)) |
| Os de `webhookHeaders` | Quando o projeto define cabeçalhos extras | Os valores definidos no projeto |

- Rejeite um `X-Sales-Timestamp` a mais de **300 segundos** do seu relógio e compare a assinatura em tempo constante, sobre os bytes do corpo como chegaram.
- Os cabeçalhos extras de `webhookHeaders` podem substituir `Content-Type` e `X-Webhook-Token`, mas nunca `X-Sales-Timestamp` e `X-Sales-Signature`: esses são sempre os do gateway.
- O [evento de teste `ping`](https://apiwpp.com/docs/webhooks/ping) traz os mesmos cabeçalhos das entregas reais.

A verificação completa, com código em Node.js, PHP e Python, está em [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).

## Próximos passos

- [Autenticação](https://apiwpp.com/docs/autenticacao): criar, rotacionar e revogar a chave que vai em `Authorization`.
- [Códigos de erro](https://apiwpp.com/docs/referencia/codigos-de-erro): cada resposta que traz `Retry-After` e o que fazer.
- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): verificar `X-Sales-Signature` passo a passo.
- [Limites](https://apiwpp.com/docs/referencia/limites): os números por trás de `X-RateLimit` e dos `429`.
