Códigos de erro · Outposted

Quando uma publicação falha, a gente sempre devolve uma mensagem clara dizendo o porquê. Esta página é o guia rápido de "deu erro X, faça Y".

90% dos erros caem em uma das situações abaixo, e quase todos têm solução rápida. Se nada bate, manda email pra suporte@outposted.one com o request_id ou content_id que aparece no painel.

Os 8 erros mais comuns

1. Chave de acesso inválida — `invalid_api_key`

A chave que você colou está errada, foi revogada, ou nem existe.

Confere se você copiou a chave inteira (32 caracteres depois de opst_live_).
Confere se não foi revogada — no painel, Configurações → Chaves de acesso.
Se não tem certeza, cria uma chave nova.

2. Texto longo demais — `caption_too_long`

Cada rede tem limite de caracteres. Você ultrapassou. Reduz ou divide em thread (Threads aceita até 25 posts encadeados).

Threads: 500 chars por post
Instagram: 2.200 chars
LinkedIn: 3.000 chars
YouTube título: 100 chars · descrição 5.000

3. Mídia grande demais — `media_too_large`

Sua foto ou vídeo passou do tamanho máximo. Comprime (HandBrake pra vídeo, TinyPNG pra imagem) ou troca formato (PNG → JPEG, MOV → MP4).

Instagram foto: 8 MB · FB foto: 30 MB
IG reel: 4 GB · LinkedIn vídeo: 5 GB · YT vídeo: 256 GB

Além do limite da rede, há um teto do Outposted: 100 MB para mídia cujo endereço não informa o tamanho do arquivo. Acontece com mídia enviada por URL externa quando o servidor de lá não diz quanto o arquivo pesa — sem esse dado, a gente precisa ler o arquivo inteiro antes de repassá-lo. Nesse caso, a mensagem do erro diz que o endereço não informa o tamanho. Para resolver:

Hospede a mídia num endereço que informe o tamanho (cabeçalho Content-Length) — aí vale só o limite da rede.
Ou envie o arquivo pelo upload do Outposted.
Ou comprima abaixo de 100 MB.

4. Formato de mídia não suportado — `media_unsupported_format`

A rede recusou o formato.

Use formatos padrão: JPEG/PNG pra foto, MP4 pra vídeo.
Vídeo vertical pra reel/short: proporção 9:16.

5. Conexão expirou ou permissão revogada — `token_expired / permission_revoked`

A permissão que você deu lá no início perdeu validade. Trocou senha da rede, ou Meta/Google forçou re-autenticação.

Vai no painel → marca → conexão da rede em questão.
Clica em Reconectar e aprova de novo.

Em segundos volta ao normal. Quem publica por ChatGPT, n8n, código vai receber token_expired até você reconectar.

6. Você publicou rápido demais — `rate_limited`

Bateu o limite de 600 chamadas por minuto do seu workspace. Espera 1 minuto. Se acontece sempre, fala com a gente em suporte@outposted.one pra subir o limite.

7. Atingiu cota da rede — `quota_exceeded`

Cada rede tem cota própria. Instagram, por exemplo, limita ~25 publicações por dia por conta.

Espera o reset (geralmente meia-noite UTC).
Distribui posts entre mais conexões se você é agência.

8. Sua marca tem mais de uma conexão nessa rede — `connections_required`

Você não disse qual usar e a marca tem duas. Olha a lista que devolvemos junto com o erro e reenvia o post escolhendo.

Sua marca tem várias conexões do Facebook. Qual destas?
- Multicargo
- Tomorrow Academy
- DNA da Persuasão

Outros erros

"Recurso não encontrado" (not_found) — Você está pedindo algo que não existe (ID errado, ou não é seu). Confere os IDs.
"Não tem permissão" (forbidden) — Sua chave é de outro workspace. Confere se você está chamando o workspace certo.
"Já foi publicado" (idempotency_conflict) — Você reusou o mesmo código de idempotência com conteúdo diferente. Use código novo ou repita exatamente o mesmo conteúdo.
"Problema do nosso lado" (server_error) — Bug nosso, já tá logado. Tenta de novo daqui um pouco. Se persistir, suporte@outposted.one com o request_id.

Catálogo completo

Pra integradores.

Formato canônico

Toda resposta de erro: error (machine-readable), message (human), request_id (rastreamento).

{
  "error": "validation_failed",
  "message": "target_platforms must contain at least 1 item",
  "request_id": "req_abc123"
}

Tabela HTTP status × error

HTTP	error	Significado	Ação
400	validation_failed	Body inválido contra schema.	Veja message com path do campo problemático.
400	invalid_request	JSON malformado, header faltando.	Cheque Content-Type + corpo.
401	invalid_api_key	Key ausente, malformada, revogada ou inexistente.	Confira header Authorization.
401	invalid_token	OAuth access_token expirou/revogado.	Re-autentique via OAuth.
403	forbidden	API key não pertence ao workspace.	Cheque wsId no path.
403	limit_reached	O plano atingiu o teto de um medidor. De ESTOQUE (marcas, conexões, armazenamento de mídia, webhooks, biblioteca de inspirações) ou POR CICLO (`criacao_de_conteudos`, uma por peça; `publicacoes`, uma por REDE — publicar em 3 redes consome 3). O corpo é o mesmo nos dois casos e traz `meter`, `limit`, `used` e `resolve`.	Leia `resolve`: `upgrade` aumenta o teto; `desativar_outra` libera vaga desativando outra no painel. Teto por ciclo volta a zero sozinho na virada do plano — apagar o que já foi criado não devolve a cota.
402	saldo_insuficiente	Uma operação que gasta CRÉDITO foi pedida e o saldo não cobre. É 402 e não 403 porque isto se resolve pagando: repetir depois de comprar crédito funciona (`recoverable: true`). O corpo traz `meter`, `modo`, `preco_unitario`, `custo_estimado` e `saldo_disponivel`.	Consulte `GET /v1/workspaces/{wsId}/wallet/preco` ANTES de pedir a operação, e `GET .../wallet` para ver o extrato. Para recarregar, `GET .../wallet/offers` devolve os pacotes à venda com o link de pagamento pronto. Ou troque de modo.
402	saldo_fragmentado	O saldo TOTAL bastaria, mas esta operação precisa sair de um lote único e nenhum é grande o bastante. Acontece no fim do ciclo, com o lote da concessão quase drenado ao lado de um avulso. O corpo traz `maior_lote_disponivel` ao lado do saldo total — é ele que limita.	Gaste ou aguarde o vencimento de um lote, ou compre crédito para ter um bloco maior.
402	lote_vencido	O lote de crédito escolhido para a operação venceu entre a escolha e a cobrança — uma corrida, e o momento em que ela acontece é a virada de ciclo. Nada foi gasto.	Tente de novo: a escolha seguinte já não vê esse lote (`recoverable: true`).
402	operacao_sem_preco	A operação existe mas ainda não tem preço publicado. Não é "de graça" — é falha fechada de propósito: um esquecimento de catálogo não pode virar produto gratuito em silêncio. Nada foi gasto.	Não é erro seu. Fale com o suporte.
404	not_found	Recurso não existe ou não é seu.	Confirme IDs.
409	idempotency_conflict	Idempotency-Key reusada com body diferente.	Use nova key ou mesmo body.
422	connections_required	Brand tem >1 conexão na mesma plataforma.	Reenvie com target_connections.
422	platform_not_supported	content_type incompatível com platform.	Veja /platforms.
422	media_too_large	Arquivo excede limite da plataforma. O teto do Outposted de 100 MB para mídia de endereço que não informa o tamanho não sai aqui: ele é detectado na publicação e aparece no job (ver tabela de jobs).	Comprima ou troque formato.
422	caption_too_long	Texto excede limite por plataforma.	Reduza ou divida em thread.
429	rate_limited	Limite 600 req/min por workspace estourado.	Veja header Retry-After.
500	server_error	Bug nosso. Logado em Sentry.	Retry com backoff + request_id em ticket.

Erros de OAuth (RFC 6749)

Endpoints /api/oauth/mcp/* seguem RFC 6749. Erros em error + error_description:

error	Descrição
invalid_request	Body malformado, campo obrigatório faltando.
invalid_client	client_id inexistente, revogado ou client_secret errado.
invalid_grant	Code expirado, já usado, ou mismatch de redirect_uri / client_id / PKCE.
unsupported_grant_type	Só authorization_code é suportado.

Erros de plataforma (jobs)

error_code	Categoria	Ação
token_expired	Auth	Reconecte via startOAuthConnection.
permission_revoked	Auth	Usuário removeu permissões na plataforma. Reconecte.
media_unsupported_format	Validação	Converta antes de enviar.
media_too_large	Validação	Comprima/reencode. Se a mídia veio de endereço que não informa o tamanho, o teto é 100 MB (do Outposted, não da rede): hospede num endereço com `Content-Length`, use o upload do Outposted ou comprima abaixo de 100 MB. Sem retry automático.
quota_exceeded	Plataforma	Atingiu limite (ex: 25/dia IG). Aguarde reset.
upstream_5xx	Transitório	Sistema faz retry automático. Sem ação.
upstream_unknown	Bug	Email pra suporte@outposted.one com job_id.
confirmacao_esgotada	Confirmação	A rede não confirmou a publicação dentro do prazo. O post pode ter saído: confira na rede antes de publicar de novo. Se a rede confirmar depois, o job vira `published` e o conteúdo recebe um evento com `corrected: true`.
confirmacao_indisponivel	Confirmação	Não foi possível perguntar à rede como ficou a publicação dentro do prazo. O post pode ter saído: confira na rede antes de publicar de novo. Se a rede confirmar depois, o job vira `published` e o conteúdo recebe um evento com `corrected: true`.
post_inexistente	Confirmação	Ao conferirmos a publicação, ela não foi encontrada, duas vezes seguidas. Confira na rede antes de publicar de novo. Se a publicação aparecer depois, o job vira `published` e o conteúdo recebe um evento com `corrected: true`.

Request-ID

Toda resposta inclui X-Request-Id. Inclua-o em qualquer ticket de suporte — faz lookup direto nos logs. Sem ele, é muito mais difícil rastrear.

Próximos passos

← Plataformas

Webhooks →

Por que meu post não foi