Autenticação

Chave de API para integrações, sessão do painel para o navegador. Como cada modo funciona, os limites de requisição e o envelope de erro que vale para toda a API.

A API aceita dois modos de acesso e nunca os dois na mesma requisição.

Chave de API

É o modo das integrações. Envie a chave no header x-access-key em toda chamada. A chave identifica um projeto: tudo o que você cria ou consulta pertence a ele.

Cabeçalho

x-access-key: pm_live_…

Regras:

A chave é exibida uma única vez, ao ser criada em Chaves de API no painel. A API guarda só o hash.
Use a chave apenas no servidor. O CORS da API não aceita x-access-key vindo de um navegador.
Revogue e crie outra sempre que houver suspeita de vazamento. Revogar é imediato e idempotente.
GET /v1/health/auth confirma que a chave é válida e devolve o projeto.

Sessão do painel

O painel fala com a mesma API usando a sessão do usuário: Authorization: Bearer <token> mais o header x-project-id para dizer em qual projeto agir. Esse modo existe para o navegador e para as rotas de conta (/v1/me, chaves de API), que só aceitam Bearer.

Se você está integrando um sistema, use a chave de API. Uma requisição com x-access-key e Authorization: Bearer ao mesmo tempo é rejeitada com 401 UNAUTHORIZED.

Limites de requisição

Os limites contam por credencial (a chave, ou o token) e por minuto. A requisição rejeitada pela autenticação também conta, para que uma chave errada não possa ser tentada sem limite.

Balde	Limite	Rotas
Padrão	300/min	Todas as rotas de recurso: contas, posts, profiles
Upload	60/min	`POST /v1/media`
Conta	60/min	`/v1/me`, organização, listar e revogar chaves
Criar chave	10/min	`POST /v1/projects/:id/api-keys`
Públicas	60/min por IP	Callback do OAuth, callbacks da Meta, spec OpenAPI

Toda resposta traz os headers x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset. Ao estourar, a API responde 429 com o código RATE_LIMIT_KEY; espere o reset antes de tentar de novo.

Além desse limite, cada conta do Instagram tem a própria cota de publicação da Meta (100 posts por 24 horas). A Postmatic verifica a cota antes de aceitar um post; se estiver esgotada, a resposta é 409 RATE_LIMIT_ACCOUNT.

Envelope de erro

Todo erro vem no mesmo formato, com um code estável para o seu código tratar e uma message para pessoas.

Exemplo de erro

{
  "statusCode": 409,
  "code": "TOKEN_INVALID",
  "message": "a conta precisa ser reconectada",
  "details": { "accountId": "int_…" }
}

Decida sempre pelo code, nunca pelo texto da message, que pode mudar. A lista completa está em Erros.

Ambientes

Cada projeto tem um environment, hoje sempre live. A chave carrega o ambiente no prefixo (pm_live_). Não existe sandbox: teste com uma conta profissional de testes e publique de verdade.