# Autenticação, erros e limites

> Como se identificar na API do Praeko (chave Bearer), o que cada escopo permite, o formato dos erros, os limites e o versionamento.

Fonte: https://praeko.app/docs/auth

Tudo o que vale para todas as rotas: como se identificar, o que cada escopo permite, o formato dos erros e quantas requisições cabem por minuto.

## Autenticação

Chave de API no cabeçalho `Authorization`, com o prefixo `Bearer`. A URL base é `https://praeko.app`; tudo é JSON em UTF-8.

**Cabeçalhos**

```text
Authorization: Bearer praeko_…
X-Praeko-Contract: en
```

| Item | Detalhe |
|---|---|
| Formato da chave | Começa com `praeko_`. Chaves antigas começam com `arauto_` e continuam valendo. |
| `X-Praeko-Contract: en` | Escolhe o contrato em inglês nos caminhos que existem nos dois contratos (`/v1/posts`, `/v1/insights`, `/v1/youtube/videos`). Sempre envie. |
| Segredo | Mostrado uma vez, ao criar. O Praeko guarda só o hash. |
| Cookie do painel | Só para o painel. Programas devem usar chave de API. |
| Agentes de IA (MCP) | O servidor MCP em `https://praeko.app/mcp` aceita a chave de API ou o login por OAuth (o agente abre uma tela de consentimento e você escolhe o acesso). Veja [Servidor MCP](https://praeko.app/docs/mcp). |

> **Guarde a chave fora do código** Use variável de ambiente ou cofre de segredos. Se vazou, revogue em Chaves de API e crie outra.

## Escopos

Cada chave tem um escopo e cada nível inclui o anterior. O escopo mínimo de cada rota aparece como selo na [referência](https://praeko.app/docs/api).

| Escopo | Permite | Rotas |
|---|---|---|
| (read) | Ler canais, posts, calendário, métricas, comentários, uso. | GET na maioria dos recursos |
| (write) | Criar, editar e cancelar posts; subir mídia; responder comentários; horários; ideias. | POST, PUT, PATCH, DELETE de conteúdo |
| (admin) | Chaves, webhooks, token do Instagram, importar métricas. | api-keys, webhooks, insights/import |

## Erros

O status HTTP é o da falha. O corpo segue sempre o mesmo envelope; `code` é estável, `message` é texto em português.

**422**

```json
{
  "error": {
    "code": "time_in_past",
    "message": "tiktok: 2026-11-01T10:00:00Z já passou ou é daqui a menos de 30 s",
    "details": {}
  }
}
```

| Status | code | Significa |
|---|---|---|
| 400 | `empty_body`, `invalid_json` | Corpo vazio ou que não é um objeto JSON. |
| 401 | `unauthorized`, `invalid_api_key`, `revoked_api_key`, `expired_api_key` | Sem chave, ou chave inexistente, revogada, expirada. Traz `WWW-Authenticate: Bearer`. |
| 403 | `forbidden` | O escopo da chave não basta. |
| 404 | `post_not_found`, `media_not_found`, `webhook_not_found`… | O recurso não existe neste workspace. |
| 409 | `channel_not_connected`, `no_slots`, `media_not_ready`… | O estado atual impede a ação. |
| 413 | `body_too_large` | O corpo passa de 1 MB. |
| 422 | `invalid_field`, `invalid_request`, `time_in_past`… | Campo inválido; `details.errors` lista todos. Campos em português são recusados. |
| 429 | `rate_limited` | Limite por minuto. Traz `Retry-After`. |
| 502 | `youtube_error`, `instagram_error`, `tiktok_unavailable`, `buffer_error` | A rede recusou; a mensagem dela vem no corpo. |

A lista completa dos códigos do contrato, com status e significado, está em [Erros e limites](https://praeko.app/docs/guides/errors-and-limits).

## Limites

| Limite | Valor |
|---|---|
| Requisições | 300 por minuto por chave (aproximado, por instância). Passou: `429` com `Retry-After`. |
| Corpo JSON | 1 MB |
| Arquivo de mídia | Até 50 MiB de uma vez (`simple: true`); acima, em partes de no mínimo 5 MiB |
| Webhooks | 10 por workspace; entrega com 10 s de limite |
| Log de uso | 30 dias, só metadados |

## Idempotência

Mande o cabeçalho `Idempotency-Key` (um UUID) em `POST`, `PATCH` e `DELETE` e uma repetição depois de uma falha de rede devolve a resposta da primeira vez, com `Idempotent-Replayed: true`, sem criar nada de novo. A chave vale 24 horas, por workspace e por rota. Chave reusada com outro pedido volta `422 idempotency_key_reuse`; primeiro pedido ainda em andamento volta `409 idempotency_in_progress`. Sem o cabeçalho nada muda. Detalhes, curl, SDK e CLI em [Repetir uma requisição](https://praeko.app/docs/guides/idempotency).

**Repetir sem duplicar**

```bash
curl -X POST https://praeko.app/v1/posts \
  -H "Authorization: Bearer $PRAEKO_KEY" -H "X-Praeko-Contract: en" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" -d @post.json
```

## Versões e changelog

A versão vai no caminho: `/v1`. Os caminhos em português continuam respondendo, marcados com `Deprecation: true` e `Link: …; rel="successor-version"`. A data para desligá-los ainda não foi fixada. O [changelog público](https://praeko.app/docs/changelog) lista as mudanças, com a data de cada uma.

## Caminhos descontinuados

Estes caminhos em português ainda funcionam e respondem com `Deprecation: true` e `Link: <novo>; rel="successor-version"`: os aliases `/v1/...` em português (por exemplo `/v1/canais`, no lugar de `/v1/channels`), `/saude` (use `/health`) e `/conexoes/:rede/retorno` (use `/connections/:network/callback`). No painel, os endereços antigos (`#/publicar`, `#/canais`, `#/conectar-agente`…) são reescritos para os novos (`#/publish`, `#/channels`, `#/connect-agent`…) e `/entrar` redireciona (301) para `/sign-in`. Mude as suas integrações para os caminhos novos. Antes de desligar qualquer um, o aviso sai aqui no [changelog](https://praeko.app/docs/changelog), com pelo menos 90 dias de antecedência; a data ainda não foi fixada.