# Cancelar da fila

Fonte: https://apiwpp.com/docs/api/mensagens/cancelar-mensagem-na-fila
Seção: Mensagens
Atualizado em: 2026-09-28

`DELETE /connections/{id}/queue/{jobId}`

Tira da fila uma mensagem que ainda não foi enviada. Só uma mensagem que ainda espera a vez pode ser cancelada: a que já está sendo enviada, já foi enviada ou já saiu da fila responde `404`. Escopo necessário: `messages:send`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador da conexão (o número) que enfileirou a mensagem. |
| `jobId` | `string · uuid` | sim | O `jobId` da resposta de `POST /connections/{id}/send`. |

## Exemplo de requisição

### cURL

```bash
curl -X DELETE \
  https://api.apiwpp.com/connections/$CONNECTION_ID/queue/$JOB_ID \
  -H "Authorization: Bearer $API_KEY"
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/queue/${jobId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->delete("https://api.apiwpp.com/connections/{$connectionId}/queue/{$jobId}");
```

### Python

```python
import requests

response = requests.delete(
    f"https://api.apiwpp.com/connections/{connection_id}/queue/{job_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | A mensagem saiu da fila e não vai ser enviada: `{"cancelled": true}`. |
| 400 | `FST_ERR_VALIDATION` | `id` ou `jobId` não é um UUID. |
| 401 |  | Sem chave de API, ou com uma chave inválida (desconhecida, revogada ou expirada). |
| 403 |  | A chave de API não tem o escopo `messages:send`; a mensagem do erro cita o escopo que falta. |
| 404 |  | A conexão não existe ou não é de quem chama (o recurso de outra pessoa responde igual a um que não existe). Também quando o job não está esperando na fila: ele não existe, já está sendo enviado, já foi enviado ou já foi cancelado. |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere Retry-After segundos. Cabeçalhos: `Retry-After`. |

### 200 OK

```json
{
  "cancelled": true
}
```

## Detalhes

O `clientRef` do envio cancelado continua reservado por 7 dias: um novo `POST /connections/{id}/send` com o mesmo `clientRef` responde `200` com o job cancelado e `"duplicate": true`, sem enfileirar nada. Para enviar de novo, use outro `clientRef`.

O registro de mensagens (`GET /messages`) passa a mostrar o envio como falho, com o motivo `Cancelado via API`. Nenhum webhook é enviado.

Guia: [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens).
