Todo erro chega no mesmo envelope. O code é estável e é por ele que o seu código deve decidir; a message é para pessoas e pode mudar.
{ "statusCode": 400, "code": "MEDIA_INVALID", "message": "imagem acima de 8 MB", "details": { "reason": "too_large" } }
details é opcional e traz o contexto que ajuda a agir: o accountId que precisa reconectar, o reason da mídia recusada, a cota da conta.
Autenticação e acesso
| Código | HTTP | Causa | O que fazer |
|---|
UNAUTHORIZED | 401 | Chave ausente, inválida, revogada ou expirada; Bearer e chave juntos; Bearer inválido. | Confira o header. Crie outra chave se a atual foi revogada. |
FORBIDDEN | 403 | O projeto ou a organização não pertence ao usuário do token. | Só no modo painel. Confira o x-project-id. |
PROJECT_REQUIRED | 400 | Modo Bearer sem x-project-id em rota de recurso. | Só no modo painel. |
RATE_LIMIT_KEY | 429 | Limite de requisições da credencial excedido. | Espere o x-ratelimit-reset. Veja Limites. |
PERMISSION_REQUIRED | 403 | A conta foi conectada sem a permissão que a rota exige (details.scope). | Reconecte a conta. |
Requisição
| Código | HTTP | Causa | O que fazer |
|---|
VALIDATION_ERROR | 400 | Campo faltando, tipo errado, fora da faixa, scheduledFor fora da janela, mediaId desconhecido. | A message indica o campo (scheduledFor: …). Corrija e reenvie. |
NOT_FOUND | 404 | Post, conta, profile ou chave que não existe neste projeto. | Confira o id. Um recurso de outro projeto também responde 404. |
Conexão de contas
| Código | HTTP | Causa | O que fazer |
|---|
PLATFORM_NOT_AVAILABLE | 403 | Plataforma diferente de instagram. | Veja o Roadmap. |
STATE_INVALID | 400 | O state do retorno do OAuth está ausente, adulterado ou passou de 10 minutos. | Inicie a conexão de novo. |
AUTHORIZATION_DENIED | 400 | O usuário negou a autorização no Instagram. | Explique o motivo e ofereça tentar de novo. |
ACCOUNT_NOT_BUSINESS | 400 | Conta pessoal. | O usuário converte para profissional nas configurações do Instagram e conecta de novo. |
TOKEN_INVALID | 409 | Token vencido ou revogado (senha trocada, app removido). Em POST /v1/posts, a conta de destino precisa reconectar. | Mande o usuário conectar a conta de novo; a conexão existente é atualizada. |
ACCOUNT_RESTRICTED | 409 | A Meta restringiu a conta. | Só o dono da conta resolve, no Instagram. |
Publicação
| Código | HTTP | Causa | O que fazer |
|---|
RATE_LIMIT_ACCOUNT | 409 | A conta esgotou a cota de publicação da Meta (100 por 24 h). details traz quotaUsage e quotaTotal. | Agende para depois ou use outra conta. |
RATE_LIMIT_APP | 503 | Limite global do app na Meta. Temporário. | A Postmatic tenta de novo sozinha nos posts já aceitos; para novos, espere alguns minutos. |
SPAM_SUSPECTED | 409 | A Meta classificou o conteúdo como spam. | Mude a legenda ou as imagens. |
MEDIA_INVALID | 400 | Imagem ou vídeo fora dos limites: missing, too_many, too_large, mime, width, aspect, duration, fps, codec, audio, bitrate ou moov em details.reason. | Veja Mídia. |
MEDIA_FETCH_FAILED | 400 | A URL respondeu erro ou não é https. | Confira a URL. |
MEDIA_UNREACHABLE | 400 | A URL não pôde ser alcançada (DNS, tempo limite, endereço privado). | Confira se é pública. |
CONTAINER_EXPIRED | 409 | A Meta demorou demais para processar a mídia. | Novas tentativas são automáticas. |
CONTAINER_STUCK | 409 | O container ficou processando (IN_PROGRESS) por mais de 1 hora sem concluir. | Terminal — crie um post novo; não há nova tentativa automática. |
MESSAGE_WINDOW_CLOSED | 409 | Mensagem direta fora da janela de 24 h desde a última mensagem do destinatário (details.recipientId, details.lastInboundAt). | Só uma nova mensagem do destinatário reabre a janela; espere ele escrever de novo. |
POST_NOT_CANCELLABLE | 409 | O post já entrou em publicação, já terminou ou o horário passou. | Nada a fazer; consulte o estado atual. |
Infraestrutura e callbacks
| Código | HTTP | Causa | O que fazer |
|---|
PLATFORM_CREDENTIALS_MISSING | 500 | Configuração do app da Meta ausente no servidor. | Falha nossa. Avise o suporte. |
SIGNED_REQUEST_INVALID | 400 | Assinatura de um callback da Meta não confere. | Só acontece nas rotas que a Meta chama. |
INTERNAL_ERROR | 500 | Erro inesperado. | Repita mais tarde; se persistir, avise o suporte com o horário. |
Erros por destino
Depois de aceito, um post não devolve mais erro HTTP: cada destino em platforms[] registra o resultado em errorCode e errorMessage. Os códigos são os mesmos das tabelas acima, mais dois que só existem nesse contexto:
errorCode | Significado |
|---|
CANCELLED | Você cancelou o post antes de publicar. |
PUBLISH_UNCONFIRMED | A Meta aceitou a publicação, mas não confirmou o resultado a tempo. O post pode existir no Instagram; verifique antes de reenviar. |
Quando repetir
- Repita com segurança:
RATE_LIMIT_KEY (depois do reset), RATE_LIMIT_APP, INTERNAL_ERROR. Use o mesmo idempotencyKey para não duplicar um post.
- Não repita sem mudar algo:
VALIDATION_ERROR, MEDIA_*, SPAM_SUSPECTED, ACCOUNT_NOT_BUSINESS.
- Precisa do usuário:
TOKEN_INVALID, ACCOUNT_RESTRICTED, AUTHORIZATION_DENIED.
