Limites e convenções

Limites de requisição e de conteúdo, paginação, datas e fusos, ids, versionamento e as convenções que valem em todas as rotas.

Limites de requisição

Contados por credencial e por minuto. Detalhes e tabela completa em Autenticação.

Balde	Limite
Padrão	300/min
`POST /v1/media`	60/min
Rotas de conta (Bearer)	60/min
Criar chave	10/min
Rotas públicas	60/min por IP

Headers em toda resposta: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset (segundos até o balde zerar). Estouro: 429 RATE_LIMIT_KEY.

Limites de conteúdo

Regra	Valor
Legenda	até 2.200 caracteres
Itens de mídia por post	1 a 10; Story exatamente 1
Contas por post	1 a 5
Imagem	JPEG, PNG ou WebP; até 8 MB; 320 a 1920 px de largura; feed 320 a 1440 px e proporção de 4:5 a 1,91:1
Vídeo	Reel até 15 min e 300 MB; Story e item de carrossel até 60 s e 100 MB
Agendamento	de 1 minuto a 75 dias à frente
Publicações por conta	100 a cada 24 horas (cota da Meta)
Nome de profile	até 120 caracteres; descrição até 500
Nome de chave	até 60 caracteres
`idempotencyKey`	até 128 caracteres

Paginação

As listagens (/v1/connect/integrations, /v1/posts) usam limit e offset e devolvem total para você saber quando parar.

Parâmetro	Padrão	Faixa
`limit`	20	1 a 100
`offset`	0	≥ 0
`sort`	`desc`	`asc` ou `desc`, pela data de criação

Formato das listagens

{ "success": true, "total": 137, "integrations": [ … ] }

GET /v1/profiles devolve todos os profiles de uma vez, sem paginação.

Datas e fusos

Toda data na API é ISO 8601. Na entrada, scheduledFor aceita Z ou offset explícito (-03:00); sem um dos dois a requisição é rejeitada.
Na saída, todas as datas vêm em UTC com Z.
timezone (IANA, como America/Sao_Paulo) é guardado junto com o post para você exibir o horário local. Ele não converte scheduledFor: o instante é o que a data com offset diz.

Identificadores

Ids são strings opacas com prefixo que indica o tipo: proj_, prf_, int_, post_, tgt_, med_, key_. Não dependa do formato além do prefixo.

profileId="null" (a string literal) nas listagens significa "sem profile". Em respostas, um campo sem valor vem como JSON null.

Convenções de rota

Prefixo /v1 em toda rota.
Barra final é opcional: /v1/posts e /v1/posts/ são a mesma rota.
Respostas de sucesso trazem success: true; criação responde 201; aceitação para processamento em segundo plano responde 202.
Rota desconhecida responde 404 NOT_FOUND no mesmo envelope de erro. Sem credencial, o 401 vem antes do 404.
CORS só está habilitado para o painel. Chamadas do navegador com x-access-key são bloqueadas de propósito.

Versionamento

A versão vive no caminho (/v1). Dentro dela, as mudanças são aditivas: campos novos podem aparecer em respostas a qualquer momento, e o seu cliente deve ignorar o que não conhece. Remover um campo, mudar um tipo ou o significado de um code só acontece em uma nova versão de caminho, com aviso prévio.

O spec OpenAPI é gerado das próprias rotas a cada deploy e é a descrição autoritativa do contrato.