Como ler o status_code do contêiner do Instagram antes de publicar

O que é o status_code do contêiner do Instagram?

Publicar no Instagram pela API acontece em duas chamadas, e o status_code do contêiner do Instagram é o campo que diz se a segunda vai funcionar. A primeira chamada cria um contêiner com POST /<IG_ID>/media. A segunda o publica com POST /<IG_ID>/media_publish. Entre elas fica um transcode assíncrono que você não vê, e a própria referência da Meta diz isso sem rodeios: "Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful."

O campo mora no nó IG Container. A Meta o define como "The container's publishing status" e você o lê com uma única requisição:

curl -X GET \
  'https://graph.instagram.com/17889615691921648?fields=status_code&access_token=IGQVJ...'

{
  "status_code": "FINISHED",
  "id": "17889615691921648"
}

O que significa cada valor de status_code?

A Meta documenta cinco valores e nenhum outro. As definições abaixo são as impressas na referência do IG Container e repetidas palavra por palavra no guia de Content Publishing.

Dois desses cinco são terminais no sentido de que nenhuma espera os muda. ERROR e EXPIRED significam os dois que o contêiner na sua mão está morto. FINISHED é o único valor que significa siga.

Há um segundo campo que vale pedir na mesma chamada. O copyright_check_status devolve matches_found como booleano e um status próprio com valor completed, error, in_progress ou not_started. Um reel pode chegar a FINISHED no status_code enquanto a checagem de direitos autorais ainda está in_progress, o que é uma das razões para uma publicação que parecia pronta ainda voltar insatisfeita.

Com que frequência a Meta manda consultar o contêiner?

A Meta dá uma única frase de orientação: "We recommend querying a container's status once per minute, for no more than 5 minutes." São cinco requisições, no total, por contêiner.

O número merece uma encarada, porque a mesma documentação fixa a vida do contêiner em 24 horas. Cinco minutos de polling cobrem cerca de 0,35 por cento da janela em que o contêiner é válido. A Meta nunca diz o que um cliente deve fazer com um contêiner que ainda está IN_PROGRESS no minuto seis. A documentação simplesmente para.

Na prática, um reel longo que ainda está transcodificando no minuto cinco continua transcodificando, e o contêiner segue bom por mais 23 horas e 55 minutos. O teto de cinco minutos soa como conselho sobre com que força martelar o endpoint, e não como afirmação sobre quando um contêiner vira caso perdido. Tratá-lo como a segunda coisa joga fora contêineres que teriam terminado.

Quanto tempo um contêiner do Instagram dura antes de expirar?

Contêineres expiram depois de 24 horas. A referência do IG User Media afirma isso na lista geral de limitações, e a definição de EXPIRED repete pelo outro lado: o contêiner "was not published within 24 hours."

A mesma lista acrescenta um segundo número que importa quando você enfileira posts em lote: "An Instagram account can only create 400 containers within a rolling 24 hour period." Isso é um orçamento de contêineres, não de publicações, e conta cada contêiner que você cria, publique-o ou não. Um laço de retry que reconstrói o contêiner a cada falha queima esse orçamento rápido.

O orçamento de publicação é uma cifra separada, e aqui o próprio guia da Meta discorda de si mesmo na mesma página. A seção Rate Limit do guia de Content Publishing diz "Instagram accounts are limited to 100 API-published posts within a 24-hour moving period." A seção Limitations do carrossel, mais abaixo na mesma página, diz "Accounts are limited to 50 published posts within a 24-hour period." As duas frases estão no ar. As duas acrescentam que um carrossel conta como um post. Quem constrói em cima disso deveria consultar GET /<IG_ID>/content_publishing_limit e confiar nisso mais do que em qualquer um dos parágrafos, que é a abordagem que adotamos no texto sobre o limite de publicação de conteúdo do Instagram e no do teto de 100 posts por 24 horas.

O que fazer quando o status_code devolve ERROR?

Peça o campo status no mesmo contêiner. A definição desse campo pela Meta é a parte útil: "Publishing status. If status_code is ERROR, this value will be an error subcode."

Então o status_code diz que algo quebrou e o status diz o quê. Os subcódigos que mais aparecem em um contêiner que falhou vêm da tabela de códigos de erro do Instagram da Meta:

O último é o honesto. O conserto recomendado pela Meta para o 2207053 é "Generate a new container and use it to try again," e ela nota que o subcódigo "should only affect video uploads."

Quatro desses sete são corrigíveis antes mesmo de você criar um contêiner, validando o arquivo contra as specs publicadas. As regras de legenda estão na nota sobre o limite de 2.200 caracteres na legenda, e as de vídeo no detalhamento sobre o que a API de Reels do Instagram aceita.

O que fazer quando o status_code devolve EXPIRED?

Começar de novo. Não existe endpoint que reviva um contêiner expirado, nem parâmetro de extensão, nem operação de atualização no nó. A referência do IG Container diz "This operation is not supported" tanto em Creating quanto em Updating e Deleting. Um contêiner é somente leitura do seu lado.

A tabela de erros da Meta confirma o remédio na coluna de solução recomendada do subcódigo 2207020, cuja mensagem diz The media you are trying to access has expired. Please try to upload again. O conserto dado é "Generate a new container ID and use it to try again."

Um subcódigo aparentado é fácil de confundir com expiração e não é a mesma coisa. O subcódigo 2207008 devolve The media builder with creation id = {creation-id} does not exist or has been expired. A Meta chama isso de "Temporary error publishing a container" e aconselha "Try again 1-2 times in the next 30 seconds to 2 minutes. If unsuccessful, generate a new container ID." Ou seja, a mensagem diz expirado e a orientação diz tentar de novo. Tente de novo antes de reconstruir.

Por que o media_publish falha quando o status_code diz FINISHED?

Porque FINISHED descreve o contêiner, não a conta. Três falhas sobrevivem a um FINISHED limpo.

O subcódigo 2207027 devolve The media is not ready for publishing, please wait for a moment, e o conserto da Meta é checar o status do contêiner e publicar quando ele disser FINISHED, o que é circular quando FINISHED é exatamente o que você acabou de ler. Trate como corrida e tente de novo.

O subcódigo 2207042 devolve You reached maximum number of posts that is allowed to be published by Content Publishing API. O contêiner está bem; a franquia diária acabou. O conselho da Meta é "Advise the app's user to try again the following day."

O subcódigo 2207050 devolve The Instagram account is restricted. A Meta explica que a conta "is inactive, checkpointed, or restricted" e que o único caminho adiante passa pelo app do Instagram, não pela API. É a mesma parede por trás da maioria das razões que as pessoas encontram quando perguntam por que não conseguem postar no Instagram.

Perguntas frequentes

Quantos valores o status_code pode devolver?

Cinco. IN_PROGRESS, FINISHED, PUBLISHED, ERROR e EXPIRED. A referência do IG Container da Meta lista exatamente esses e nenhum outro.

Um contêiner de foto precisa de polling?

A seção de troubleshooting da Meta trata o polling de status em torno de vídeo, já que contêineres de imagem se resolvem na chamada de criação. Pedir o status_code em um contêiner de imagem ainda funciona e ainda devolve um dos cinco valores.

Quanto esperar entre as consultas?

Uma vez por minuto. O texto exato da Meta é "We recommend querying a container's status once per minute, for no more than 5 minutes."

O que acontece com um contêiner que você nunca publica?

Ele expira 24 horas depois da criação e conta contra o limite de 400 contêineres por 24 horas móveis. Contêineres não publicados não contam contra o limite de publicação.

Dá para apagar um contêiner e liberar cota?

Não. O nó IG Container lista Deleting como "This operation is not supported." Contêineres se limpam sozinhos quando expiram.

Qual campo diz por que a publicação falhou?

O campo status, e não o status_code. A Meta documenta que, quando o status_code é ERROR, o valor de status é um subcódigo de erro que você então procura na tabela de códigos de erro do Instagram.

Quantos dos subcódigos de ERROR dá para evitar antes de criar um contêiner?

Quatro dos sete subcódigos da tabela da Meta dá para evitar antes mesmo de o contêiner existir. Conferir o arquivo, as dimensões e o tamanho da legenda contra as especificações publicadas pela Meta pega formato de vídeo errado, proporção fora da faixa, imagem grande demais ou legenda longa demais antes do upload, já que essas condições já são conhecidas antes de o contêiner ser criado.

Um contêiner pode chegar a FINISHED antes de a checagem de direitos autorais terminar?

Pode. Um reel pode chegar a FINISHED no status_code enquanto o copyright_check_status ainda está in_progress, então o contêiner parece pronto antes de a checagem de direitos autorais ter terminado de fato. Esse campo devolve matches_found como booleano e um status completed, error, in_progress ou not_started, que vale pedir junto com o status_code antes de publicar.

Por que a própria documentação da Meta se contradiz sobre o limite de publicação?

A seção Rate Limit do guia Content Publishing limita as contas a 100 posts publicados pela API dentro de um período móvel de 24 horas, enquanto a seção Limitations sobre carrosséis, mais abaixo na mesma página, fala em limite de 50 posts publicados em 24 horas. As duas frases continuam no ar. Consultar GET /<IG_ID>/content_publishing_limit e confiar nessa resposta em vez de qualquer um dos parágrafos evita ficar no chute.

O subcódigo 2207008 quer dizer que o contêiner expirou?

Não, mesmo a mensagem dizendo "has been expired". A Meta classifica 2207008 como um erro temporário e recomenda tentar de novo uma ou duas vezes nos 30 segundos a 2 minutos seguintes antes de criar um contêiner novo. Já um status EXPIRED de verdade não tem nenhuma tentativa nova possível.