Autenticação e convenções

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:

{
  "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:

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

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