API do Instagram para Publicar Conteúdo: 6 Erros que Enfrentei e Como Resolvi

Depois de muitos projetos com a WhatsApp Business API, chegou a vez de implementar a API do Instagram para publicar conteúdo automaticamente: posts, carrosséis e Reels saindo direto do sistema, sem ninguém abrir o app.

A documentação da Meta faz parecer simples: criar um container de mídia, publicar o container, pronto. Na prática, travei em pelo menos seis pontos. Aqui está cada problema e a solução que funcionou.

Como funciona a publicação via API do Instagram

O fluxo da Instagram Content Publishing API tem duas etapas:

1. POST /<IG_ID>/media com a image_url (ou video_url) e a legenda. A resposta traz o ID do container.
2. POST /<IG_ID>/media_publish com o creation_id desse container.

Entre uma etapa e outra, a Meta baixa e processa a mídia. Quase todos os erros que vi nascem dessa assincronia.

Erro 1: token inválido (190) mesmo com permissão aprovada

Meu primeiro bloqueio foi um Invalid OAuth access token logo na criação do container. O token era válido, mas eu misturei os dois tipos de login:

• Login do Instagram (Instagram Business Login): token do usuário do Instagram, host graph.instagram.com, permissão instagram_business_content_publish.
• Login do Facebook: token de Página, host graph.facebook.com, permissões instagram_content_publish e pages_read_engagement.

Solução

Escolha um caminho e use o host e as permissões dele do começo ao fim. Confirme também que a conta é profissional (Empresa ou Criador). Contas pessoais não publicam via API. O token de longa duração expira em 60 dias, então agende a renovação. Detalhei a estratégia em erros de autenticação e token expirado, e ela vale igualmente aqui.

Erro 2: image_url que a Meta não consegue baixar

O container era criado com erro, sem mensagem clara. A imagem estava num bucket privado com URL assinada de 5 minutos. Outros devs relatam o mesmo usando links do Google Drive, Dropbox e Imgur.

Solução

A Meta faz um cURL da mídia no momento da tentativa, então ela precisa estar em um servidor público e responder com o arquivo direto, sem redirecionamento para uma página HTML. Outros detalhes que me pegaram:

• O único formato de imagem aceito é JPEG. PNG e WebP precisam ser convertidos antes.
• URL assinada só funciona se continuar válida até o container ficar pronto.

Erro 3: proporção da imagem inválida (36003)

Banners em 16:9 passavam e artes em 9:16 falhavam com The submitted image with aspect ratio ... cannot be published.

Solução

Para o feed, a proporção precisa estar entre 4:5 e 1.91:1. Eu valido antes de chamar a API e recorto quando necessário:

const ratio = width / height
if (ratio < 0.8 || ratio > 1.91) throw new Error(`Proporção ${ratio.toFixed(2)} fora de 4:5–1.91:1`)

Em carrossel, todas as imagens seguem o recorte da primeira, então padronize o lote inteiro.

Erro 4: "Media ID is not available" (9007 / 2207027)

Este foi o mais chato, porque era intermitente. Imagens leves publicavam; Reels e carrosséis falhavam com:

{ "error": { "message": "Media ID is not available", "code": 9007, "error_subcode": 2207027 } }

O motivo: eu chamava media_publish logo após criar o container, antes de a Meta terminar o processamento.

Solução

Consulte o status_code do container e só publique quando estiver FINISHED. A própria Meta recomenda checar uma vez por minuto, por no máximo cinco minutos:

async function waitContainer(id, token) {
  for (let i = 0; i < 5; i++) {
    const res = await fetch(`https://graph.instagram.com/${id}?fields=status_code&access_token=${token}`)
    const { status_code } = await res.json()
    if (status_code === 'FINISHED') return
    if (status_code === 'ERROR' || status_code === 'EXPIRED') throw new Error(status_code)
    await new Promise((r) => setTimeout(r, 60_000))
  }
  throw new Error('Container não ficou pronto em 5 minutos')
}

Se der ERROR, crie um novo container em vez de insistir no mesmo. Containers não publicados em 24 horas ficam EXPIRED.

Erro 5: vídeo e Reels com formato não suportado (2207026)

Vídeos exportados por uma ferramenta de edição falhavam com The video format is not supported.

Solução

Use MP4 ou MOV, com vídeo em H.264 e áudio em AAC. No meu caso, normalizar todo upload com FFmpeg antes de expor a URL resolveu de vez. Lembre que Reels levam mais tempo em IN_PROGRESS, então o polling do erro anterior é obrigatório aqui.

Erro 6: limite de publicações em 24 horas (2207042)

Em um teste de agendamento em massa, a conta parou de publicar no meio do lote.

Solução

A API permite no máximo 100 publicações por conta em 24 horas (janela móvel), e carrossel conta como um post. Em vez de fixar esse número no código, consulte o uso atual antes de publicar:

GET /<IG_ID>/content_publishing_limit?fields=quota_usage,config

Se o sistema permite agendamento, aplique o limite também do seu lado, enfileirando o excedente para a próxima janela.

Checklist antes de publicar via API

• Conta profissional e permissão instagram_business_content_publish aprovada
• Host certo para o tipo de token
• Mídia pública, JPEG ou MP4/MOV
• Proporção entre 4:5 e 1.91:1
• Polling do container até FINISHED
• Cota checada em content_publishing_limit

Conclusão

A API do Instagram é estável quando você respeita a assincronia: criar o container, esperar o processamento e só então publicar. Os demais erros são validações que dá para antecipar antes de chamar a Meta.

Está integrando a publicação no Instagram ou a API da Meta no seu produto? Fale comigo e eu ajudo a colocar no ar.