Códigos de erro da API do Instagram: quais repetir

Toda falha de publicação no Instagram termina em uma de quatro ações: repetir, corrigir a requisição, passar para o responsável pela conta, ou parar e encaminhar. Acertar essa decisão é o trabalho inteiro. Se você repete algo permanente, gasta cota em uma requisição que nunca vai funcionar. Se desiste de algo temporário, perde uma publicação que sairia na segunda tentativa.

A Meta documenta o que cada código de erro significa. Ela não documenta qual das quatro ações tomar, e sua tabela de referência não tem nenhuma coluna de erro temporário. Este guia liga os códigos que a Meta publica hoje a uma decisão, usando as quatro categorias de falha com as quais a API de publicação unificada da InvisibleAPI já classifica cada publicação. Todos os códigos abaixo foram lidos na documentação da Meta em 14 de setembro de 2026, e as páginas estão no final.

As quatro decisões por trás de cada erro de publicação no Instagram

A InvisibleAPI classifica cada falha de publicação em uma de quatro categorias. Elas não são níveis de gravidade. Cada uma aponta um responsável diferente e um próximo passo diferente.

Leia a tabela de novo pelo lado do leitor. As categorias um e três chegam as duas como um erro em formato 400 vindo do Instagram, e as duas são permanentes para a requisição do jeito que ela está escrita. A diferença é quem consegue resolver. Essa distinção é a que uma tabela de códigos crua não consegue dar, e é a que decide se o seu produto mostra uma mensagem de validação ou um alerta pedindo que alguém faça login.

Por que a referência de erros da Meta não decide por você

A documentação da Meta é precisa e detalhada. Ela só foi feita para responder outra pergunta. Três coisas atrapalham quem quer usá-la como política de repetição.

Os códigos ficam em três páginas separadas. Subcódigos de publicação como 9007 e 2207027 estão na referência de códigos de erro do Instagram. Os códigos 190 e 368 estão no guia de tratamento de erros da Graph API. Os códigos 4, 17 e 32 são definidos na página de limites de requisição. Quem recebe um código 4 puro e quem recebe um código 4 com subcódigo 2207051 têm problemas diferentes e precisam de páginas diferentes.

Não existe classificação de erro temporário por código. A referência traz uma mensagem e uma ação recomendada em prosa. A palavra “transient” aparece no exemplo de resposta, não na tabela. As respostas de erro da Meta carregam sim um booleano is_transient ao lado de error_user_title e error_user_msg, então o sinal existe no momento da falha. Ele simplesmente não é algo que você consulte com antecedência para montar um switch.

As ações recomendadas não são intervalos. “Tente novamente” aparece em vários códigos sem nenhuma indicação de quanto esperar. Em toda a tabela de publicação do Instagram existe exatamente um código com uma janela concreta: o código 24 com subcódigo 2207008, onde a Meta indica repetir uma ou duas vezes entre 30 segundos e 2 minutos.

Códigos de erro de publicação do Instagram, agrupados pelo que fazer

Abaixo estão os códigos que a Meta documenta para publicação de conteúdo, ordenados pela decisão e não pelo número. Onde a Meta indica o comportamento de forma explícita, isso está marcado. No resto, o agrupamento é a nossa leitura da ação recomendada pela Meta, e vale tratar o campo is_transient em tempo de execução como a autoridade quando os dois discordarem.

Corrija a requisição, não repita

Correspondem a invalid_publish_data. O mesmo conteúdo vai falhar do mesmo jeito para sempre.

A última linha merece uma segunda olhada. Uma URI que não esteja publicamente acessível falha aqui, e nenhuma quantidade de repetições torna um bucket privado público. A mídia precisa ser servida a partir de uma URL pública, e essa é uma restrição que vale considerar no projeto em vez de descobrir em produção.

Repita após esperar

Correspondem a retryable_provider_failure.

O 9007 é o mais mal tratado com frequência. Na verdade ele nem é uma falha: o contêiner de mídia ainda está processando. A própria orientação de publicação da Meta é consultar o status do contêiner e publicar quando ele marcar FINISHED, verificando cerca de uma vez por minuto durante no máximo cinco minutos. Os status do contêiner são EXPIRED, ERROR, FINISHED, IN_PROGRESS e PUBLISHED. Recriar o contêiner diante de um 9007 coloca na fila um segundo upload para uma publicação que ia dar certo.

O responsável pela conta precisa agir

Correspondem a provider_action_required. O seu laço de repetição não resolve nenhum deles.

O código 190 é a falha mais comum em uma integração de vida longa, e é o exemplo mais claro de por que um laço de repetição é a ferramenta errada. O token acabou. A conta precisa ser reconectada antes que qualquer outra coisa funcione, que é o que o guia de reconexão e scopes cobre. Uma permissão que expira não quebra a conta em si, porque cada concessão de credencial é separada, então outra concessão válida na mesma conta continua publicando.

Encaminhe

platform_software_failure não tem nenhum código correspondente na Meta, e é exatamente por isso que ela existe. Ela cobre o caso em que a requisição era válida, a plataforma estava saudável, e mesmo assim algo no meio quebrou. O Instagram não tem um código para isso, porque do lado do Instagram não aconteceu. Sem uma quarta categoria, falhas desse formato são arquivadas errado como temporárias e repetidas para sempre, ou arquivadas errado como erros de quem chamou e mostradas a um usuário que não pode fazer nada a respeito. Na InvisibleAPI elas vão para o suporte técnico em vez de para o responsável pela conta.

Erros de limite são um caso à parte

Erros de limite podem ser repetidos, mas não agora, e a espera é a resposta inteira. Tratá-los como uma falha temporária qualquer é o jeito de uma integração ficar bloqueada por mais tempo.

O limite de publicação. A documentação de publicação de conteúdo da Meta indica 100 publicações via API dentro de uma janela móvel de 24 horas, e um carrossel conta como uma única publicação. Ultrapassar isso retorna o código 9 com o subcódigo 2207042, e a orientação da Meta é repetir no dia seguinte. O número de 25 publicações por dia ainda aparece em muito material de terceiros. Não é o que a documentação diz hoje, então planeje com 100 e confirme o número você mesmo antes de construir um agendador em cima disso.

Os limites de requisição. O código 4 é o limite no nível do aplicativo, o 17 no nível do usuário, o 32 o limite da Pages API, o 613 um limite personalizado e o 80002 o limite por caso de uso de negócio do Instagram. A instrução da Meta quando você é limitado é direta e vale seguir: pare de fazer chamadas, porque continuar aumenta o tempo até que elas voltem a funcionar. Os cabeçalhos X-App-Usage e X-Business-Use-Case-Usage carregam o seu consumo atual, e o segundo inclui estimated_time_to_regain_access em minutos. Esse campo é o único número de espera concreto que a Meta publica, então ele ganha de qualquer intervalo que você fosse chutar.

O seu próprio teto. Publicando pela InvisibleAPI, cada conta conectada pode publicar 100 publicações por período de faturamento, e um endpoint de limites informa o uso em tempo real para que o seu código consulte antes de iniciar um lote. Verificar o limite antes sai mais barato que uma fila de jobs que falham no provedor. Se o que trouxe você aqui foi a questão do volume, como funciona o preço por volume explica contra o que a conta é medida, e o guia de preços da API do Instagram cobre a comparação de custos mais ampla.

Lógica de repetição que lê a categoria, não o número do código

Uma política de repetição construída sobre uma lista fixa de inteiros apodrece. A Meta não publica um mapa estável de erros temporários, subcódigos são adicionados, e um código que se comporta de um jeito na publicação se comporta de outro nos limites de requisição. A lista que você escreveu em janeiro para de bater com a realidade sem que nada avise.

Baseie a decisão na classificação. Crie o job:

curl -X POST "https://api.invisibleapi.ai/api/v1/organizations/$ORGANIZATION/publishing/jobs" \
  -H "Authorization: Bearer $INVISIBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": ["acct_ig_01"],
    "caption": "New drop, live now.",
    "mediaItems": [{ "mediaType": "image", "sourceUrl": "https://cdn.example.com/drop.jpg" }],
    "clientRequestId": "drop-0914-ig"
  }'

Um job que falha volta com a categoria, e com uma entrega para cada destino:

{
  "id": "job_01K2M4P7",
  "status": "failed",
  "clientRequestId": "drop-0914-ig",
  "deliveries": [
    {
      "target": "acct_ig_01",
      "platform": "instagram",
      "status": "failed",
      "failureCategory": "retryable_provider_failure"
    }
  ]
}

Aí a decisão é um switch sobre quatro valores em vez de uma tabela de consulta de inteiros:

type Category =
  | "invalid_publish_data"
  | "retryable_provider_failure"
  | "provider_action_required"
  | "platform_software_failure";

export function decide(category: Category) {
  switch (category) {
    case "retryable_provider_failure":
      return { retry: true, backoffMs: 60_000 };
    case "invalid_publish_data":
      return { retry: false, notify: "developer" };
    case "provider_action_required":
      return { retry: false, notify: "account_owner" };
    case "platform_software_failure":
      return { retry: false, notify: "support" };
  }
}

Repetir só é seguro porque a chamada de criação carrega clientRequestId. Essa é a parte que quase todo conselho sobre repetição deixa de fora. Quando uma requisição estoura o tempo limite você não consegue distinguir uma chamada que falhou de uma que funcionou e perdeu a resposta, então repetir às cegas é jogar uma moeda sobre uma publicação duplicada. Uma chave de idempotência tira a moeda do ar: a chamada repetida não publica duas vezes. Se você quer a versão de varredura e repetição como uma construção funcionando, o modelo de recuperação de publicações que falharam é a receita.

Vale conhecer os status do job antes de escrever o laço: pending, scheduled, processing, preparing, submitted, polling, published, partial_failure, failed, action_required e canceled. Repare que action_required é um status final próprio, então um job à espera do responsável pela conta nunca fica numa fila de repetição fingindo estar em andamento.

Os erros que você consegue parar antes de chegarem ao Instagram

Volte à primeira tabela deste artigo. Quase toda linha é uma regra que poderia ter sido checada antes de a requisição sair do seu prédio. Tamanho da legenda, proporção, número de itens do carrossel e formato de vídeo são todos conhecidos de antemão.

É para isso que serve a validação prévia. Cada adaptador de plataforma valida as próprias regras antes de enviar qualquer coisa, então uma violação falha com uma chave de erro específica em vez de uma ida e volta ao provedor. Um exemplo real é publishing.validation.media_items.media_type_unsupported, que pega um tipo de mídia não suportado na porta.

O efeito prático é que uma família inteira de códigos da Meta para de aparecer nos seus registros, e os que aparecem são de fato sobre a plataforma e não sobre o seu conteúdo. Isso também muda onde o erro aparece: na criação do job, onde o seu código ainda tem o contexto, e não minutos depois em um retorno assíncrono.

Quando um job aponta para várias contas

Um job de publicação pode apontar para muitas contas conectadas ao mesmo tempo, e o resultado por destino fica nas entregas do job. Isso importa mais do que parece, porque o mesmo conteúdo pode passar em uma plataforma e falhar em outra. Uma legenda de 500 caracteres publica no Instagram e falha na regra de 280 caracteres do X, no mesmo job.

Um único status de job não dá conta disso, e é por isso que partial_failure existe como status próprio. Se você lê as entregas e não apenas o job, obtém uma resposta por conta: qual destino publicou, qual falhou na validação prévia e sob qual categoria. Para uma agência que distribui uma publicação de cliente por uma dúzia de contas, essa é a diferença entre um relatório útil e um ponto vermelho.

Pare de adivinhar quais falhas o seu código deve repetir

Os códigos de erro da API do Instagram dizem o que deu errado. Uma classificação diz ao seu código o que fazer em seguida, e é isso que transforma uma publicação que falhou em uma recuperada em vez de um alerta que alguém precisa ler. Conecte uma conta do Instagram, crie um job e deixe as categorias conduzirem a sua lógica de repetição em vez de uma lista de inteiros que você tem que manter. Cada conta começa com um teste gratuito de 7 dias.

Fontes

As quatro páginas foram consultadas em 14 de setembro de 2026.

• Referência de códigos de erro da plataforma do Instagram, para todos os códigos e subcódigos de publicação acima
• Guia de publicação de conteúdo do Instagram, para o limite de 100 publicações em uma janela móvel de 24 horas e os status do contêiner
• Tratamento de erros da Graph API, para os códigos 1, 2, 4, 17, 190, 368 e 506
• Limites de requisição da Graph API, para os códigos 4, 17, 32, 613 e 80002 e os cabeçalhos de uso