Erros comuns da API do Instagram

• 190 — Token de acesso inválido ou expirado. Subcódigos comuns: 460 (senha ou configuração de segurança mudou desde que o token foi emitido), 463 (token expirado), 467 (token inválido — frequentemente emitido para outro app ou já revogado). Exige reconectar a conta; nenhuma quantidade de novas tentativas resolve.
• 102 — Chave de sessão inválida ou não é mais válida. Costuma aparecer com um token que era válido recentemente mas foi invalidado do lado do servidor (por exemplo, o usuário removeu o acesso do seu app nas configurações da conta da Meta).
• 2500 — "Erro validando parâmetros" genérico. Esse código cobre um leque amplo de requisições malformadas, não só autenticação — inclui casos de criação de container de mídia detalhados na seção abaixo.

• 10 — Permissão negada. O token é válido, mas o app ou os escopos concedidos não cobrem a ação tentada — na maioria das vezes falta um escopo de negócio como instagram_business_content_publish ou instagram_business_manage_comments.
• 200 — Erro de permissões genérico. Um balde mais amplo que o código 10; pode aparecer quando o papel da conta conectada ou o status de App Review do app não cobre a operação pedida, mesmo que o escopo específico tenha sido tecnicamente concedido.

• 2500 — "An ID has already been specified" e outras falhas de validação de parâmetro durante a criação do container. A Meta não publica uma lista definitiva de causa raiz para essa mensagem, e relatos públicos sobre o gatilho exato variam; a causa mais bem documentada e verificável de falha na criação de container em geral é uma URL de mídia que os servidores da Meta não conseguem buscar (não publicamente acessível, tipo de conteúdo errado, ou URL assinada expirada).
• 100 (subcódigo 33) — Objeto não existe, ou não pode ser carregado com as permissões atuais. Em um fluxo de publicação, normalmente significa um ID de container inválido ou já expirado, ou um ID do tipo de nó errado.
• 9007 (subcódigo 2207027) — "The media is not ready for publishing." A própria documentação da Meta trata isso como um estado de "ainda não pronto" para tentar de novo após uma pequena espera; na prática também é amplamente reportado para um container que já expirou ou já foi publicado — trate como "este container não está publicável agora" em vez de assumir qual dos três é, sem checar o status_code primeiro.
• Container com status_code: ERROR — não é um código de erro de topo, e sim um dos cinco estados (IN_PROGRESS, FINISHED, PUBLISHED, EXPIRED, ERROR) que a Meta documenta para o próprio container. Significa que o processamento falhou depois da criação — diferente de um container apenas lento.

• 4 — Limite de requisições do app atingido. Um throttle no nível do seu app da Meta, ligado ao volume total de chamadas em todas as contas conectadas, não a um único usuário.
• 17 — Limite de requisições do usuário atingido. Restrito a uma conta conectada específica, em vez do app inteiro.
• 9 (subcódigo 2207042) — "Você atingiu o número máximo de posts permitidos pela Content Publishing API." Diferente do rate limit genérico: veja o guia dedicado sobre o limite de publicação para o número atual documentado pela Meta e como consultar o consumo de uma conta específica.

Em vez de cada integração precisar aprender esse catálogo de códigos por conta própria, o PostGate traduz o erro específico da plataforma para um envelope estruturado único, com um código estável, retryable explícito e um request_id para correlacionar com o log de entrega do post. profile_disconnected pede reconexão, platform_content_rejected pede conteúdo diferente, e rate_limited pede backoff — sem que o seu código precise saber o código numérico exato que a Meta devolveu por trás.