# Autenticação e convenções

> Chave de API, limites de taxa, formato de erro, paginação e idempotência.

Fonte: https://metahub.matratecnologia.com/docs/autenticacao

Toda rota de `/v1` exige uma chave de API no header:

```
Authorization: Bearer mh_live_...
```

- A chave é criada pela equipe Matra e entregue em claro uma única vez: guarde-a num cofre de segredos. Chaves de produção começam com `mh_live_`.
- Uma chave pertence a um app. Revogar a chave ou desativar o app a invalida na hora.
- Sem chave, com chave inválida, revogada ou de app inativo, a resposta é sempre a mesma:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "INVALID_API_KEY",
  "message": "..."
}
```

com o header `WWW-Authenticate: Bearer`. Decida pelo `code`, nunca pela `message` (ela vem traduzida conforme `Accept-Language`).

- Recurso de outro app responde **404**, nunca 403. O 404 de workspace traz `code: "WORKSPACE_NOT_FOUND"`, o de entrega `code: "DELIVERY_NOT_FOUND"` e o de conexão `code: "CONNECTION_NOT_FOUND"`, no mesmo formato do 401.
- A API é server-to-server: não chame de navegador e mantenha a chave só no backend.

## Limites de taxa

| Limite | Valor padrão | Balde |
|---|---|---|
| Por IP, antes da autenticação | 12 000 requisições por minuto | IP de origem (chave ausente ou inválida também conta) |
| Por chave, rotas em geral | 600 requisições por minuto | id da chave |
| Por chave, envio de mensagem e confirmação de leitura | 4 000 requisições por minuto | id da chave |
| Por chave, upload de mídia | 30 requisições por minuto | id da chave |
| Por chave, criar, excluir e sincronizar template | 30 requisições por minuto | id da chave |
| Uploads de mídia simultâneos | 2 por app (8 no hub inteiro) | app consumidor |

Estourou: `429` com o header `Retry-After` (segundos). Espere esse tempo antes de tentar de novo. Upload acima do limite de simultâneos responde `429` com `code: "MEDIA_UPLOAD_BUSY"` e `Retry-After: 5`; limite da Meta na criação ou exclusão de template responde `429` com `code: "META_RATE_LIMITED"`. O `429` do limite por chave não traz `code`: trate qualquer `429` pelo `Retry-After`.

Além dos limites da API, o envio tem vazão por número: o hub segura cada número em até 64 mensagens por segundo (16 em número Coexistence), abaixo dos 80 e 20 mps da Meta, que contam também as mensagens recebidas. O excedente espera na fila do hub; não é recusado.


## Paginação


Listagens aceitam `page` (padrão 1) e `limit` (padrão 20, máximo 100) e respondem:

```json
{
  "data": [],
  "meta": { "total": 0, "page": 1, "limit": 20, "totalPages": 0, "hasNext": false }
}
```

A ordem é do mais recente para o mais antigo (`createdAt`).