Os erros retornam um status code de 400, 401, 402, 403, 404, 429, 500, 502, 503 ou 504. Sucesso retorna
status code 200. Consulte aqui para detalhes.
- O campo
errorscontém o array de erros, um por rede social que teve um erro. - O
actionrefere-se ao tipo de erro retornado. - O campo
statusde nível superior será “error” se a chamada da API falhar. Por exemplo, para uma chamada /post, se todas as publicações nas redes sociais tiverem sucesso, o campostatusserá “success”; caso contrário, o campo status será “error”. - O campo
codecontém o código de erro de referência do Ayrshare. - O campo
messagetraz os detalhes específicos do erro.
Tratando erros
Você deve tratar todas as respostas de erro e tomar a ação apropriada. Ocorreu um erro se:- O código de retorno da resposta não é
200 - O status da resposta JSON é
error
400 Bad Request.
400 Bad Request:
Erros de conteúdo duplicado ou semelhante
Antes de um post chegar à rede social, a Ayrshare o compara com os seus outros posts e rejeita conteúdo idêntico ou quase idêntico com o código137. Essa verificação é da própria Ayrshare, portanto um post pode ser rejeitado mesmo quando a rede o teria permitido. Ela não vale para todas as plataformas — veja as exceções abaixo.
scheduleDate — 24 horas antes até 24 horas depois. Como a janela olha para frente além de para trás, um post pode ser rejeitado por causa de outro agendado depois dele, e não apenas antes.
O que é comparado.
- A comparação é feita por perfil de usuário e por plataforma. O mesmo texto enviado para X/Twitter e para o LinkedIn não é duplicado de si mesmo, e dois perfis de usuário diferentes não entram em conflito.
- O X/Twitter é a exceção, mas apenas para duplicidades exatas: um post idêntico também é verificado em relação a todos os perfis de usuário da mesma conta, porque o X não permite o mesmo conteúdo em vários handles. Correspondências quase idênticas (semelhança) continuam restritas ao único perfil de onde o post foi feito.
- Pinterest, Reddit e Telegram não passam por verificação de duplicidade.
Códigos de erro específicos do Instagram
Os códigos de erro a seguir fornecem detalhes específicos sobre falhas de publicação no Instagram, substituindo, sempre que possível, o erro genérico 138. Código 435 — Rate Limit do Instagram (HTTP 429) Contas profissionais do Instagram (Business / Creator) estão sujeitas a um limite móvel de 50 publicações a cada 24 horas na Content Publishing API da Meta (contas pessoais não podem publicar via API e, portanto, nunca atingem esse limite). Quando o limite é excedido, a Meta retorna um erro de limite de taxa. O Ayrshare também exibecode: 435 quando o endpoint de publicação da Meta retorna HTTP 429 diretamente ou quando o subcódigo de erro subjacente (1390008) indica um throttle de publicação / comentário.
Retry-After, o valor (em segundos) é repassado no campo details — aguarde pelo menos esse tempo antes de reenviar.
Código 436 — Timeout de processamento de mídia no Instagram (HTTP 400)
O Instagram demorou demais para processar a mídia enviada. Isso pode acontecer com arquivos de vídeo grandes ou durante períodos de alta carga nos servidores da Meta.
instagramOptions.trialParams é fornecido em uma requisição /post, mas graduationStrategy está ausente, null ou é uma string vazia. Trial reels exigem uma estratégia de graduação explícita — consulte Trial Reels.
instagramOptions.trialParams.graduationStrategy como "MANUAL" ou "SS_PERFORMANCE" e tente novamente, ou remova trialParams se você não pretendia publicar um trial reel.
Código 448 — Trial Reels do Instagram: graduationStrategy inválido (HTTP 400)
Retornado quando graduationStrategy está presente, mas não é exatamente "MANUAL" ou "SS_PERFORMANCE". A verificação diferencia maiúsculas e minúsculas — valores como "manual" ou "ss_performance" são rejeitados. O campo details ecoa o valor rejeitado (truncado em 64 caracteres) para ajudar no debug.
graduationStrategy como exatamente "MANUAL" ou "SS_PERFORMANCE" (maiúsculas, tipo string).
Código 449 — Trial Reels do Instagram: mídia incompatível (HTTP 400)
Retornado quando a mídia ou o formato da publicação não é elegível para um trial reel. Trial reels devem ser um único vídeo .mp4 ou .mov — carrosséis (mais de uma URL), stories (instagramOptions.stories: true) e extensões que não sejam vídeo são todos rejeitados. O campo details esclarece qual subcaso foi acionado.
.mp4 ou .mov sem a flag stories: true. Remova entradas adicionais de mediaUrls ou remova trialParams se pretendia fazer uma publicação normal de carrossel/story.
Código 258 — Erro de estado da conta do Instagram (HTTP 400)
Uma falha geral de estado da conta do Instagram com a mensagem base “Error with Instagram.”. Isso aparece quando a Meta rejeita a requisição devido ao estado da conta do Instagram conectada, e não ao conteúdo da publicação.
error_subcode subjacente da Meta é 2207085 (“Generic Internal Error”), a falha é transitória e do lado da Meta. A Ayrshare tenta publicar novamente de forma automática por até cerca de 50 segundos antes de retornar o erro, e a resposta define retryAvailable: true. Ela não define relink: true — revincular a conta não resolve essa condição. Quando a Meta fornece um fbtrace_id, ele é retornado em details:
2207085, tente publicar novamente em alguns minutos — é uma condição do lado da Meta que costuma se resolver sozinha, e revincular não corrige. Somente se o erro persistir por mais de 24-48 horas, oriente o usuário a desvincular e revincular a conta do Instagram em Social Accounts, concedendo todas as permissões solicitadas, ou entre em contato com o suporte da Meta com o fbtrace_id de details. Para outros erros de estado da conta, verifique se a conta do Instagram está em boa situação na Meta e tente novamente.
Retry disponível
Às vezes as redes sociais têm um erro irrecuperável, como problemas em seus servidores, e a chamada acaba falhando mesmo após várias tentativas. Nesses casos, nosso sistema determinará se o erro é passível de nova tentativa e, se for, o camporetryAvailable será true.
Erros de Áudio de Reels do Instagram
Esses códigos cobrem a anexação de música a um Reel do Instagram cominstagramOptions.audioConfiguration, além dos endpoints de pesquisa de áudio e consulta de áudio.
O código 518 chega em
postIds[].warnings[], não em errors[]. O Instagram permite uma faixa por Reel, então, quando audioConfiguration e audioName são enviados juntos, audioConfiguration vence e audioName é descartado. A resposta ainda é status: "success" com um HTTP 200 — trate o 518 como informativo e não falhe por causa dele. O aviso fica aninhado na entrada de postIds daquela plataforma, e não no nível superior, e carrega feature: "audioName".A validação de volume reporta o
101 genérico, não um código dedicado. audioVolume e videoVolume devem ser inteiros de 0 a 100. Um decimal, uma string numérica como "80", um número fora do intervalo ou um null explícito retorna code: 101 com o limite nomeado em details, antes de o Instagram ser chamado. Omita o campo em vez de enviar null.Erros de Private Reply (DM em Comentário) de Automation
Esses códigos aparecem em automações acionadas por comentário (comment_keyword) quando a private reply que carrega a DM não pode ser enviada. Eles aparecem como a linha de activity com status: "failed" e o motivo em actionResults[].errorDetails.
Nenhum deles é reenviado automaticamente — a Send API do Instagram não tem chave de idempotência, portanto um retry automático corre o risco de entregar a DM duas vezes. O tratamento varia por código (veja Ação abaixo): a maioria é permanente para aquele comentário específico, o 492 exige a reconexão da conta e o 493 é liberado por conta própria quando o limite horário é redefinido.
O código 491 cobre várias causas que o Instagram não distingue, e o 490 é a exceção mais restrita. O Instagram retorna um único erro compartilhado para um comentário com mais de 7 dias, um comentário que já recebeu uma resposta (apenas uma private reply por comentário é permitida), um comentário deletado e um autor de comentário que bloqueia solicitações de mensagem. Todos esses reportam
491.O 490 é reportado apenas no caso mais restrito em que o Instagram identifica o ID do comentário como inválido de forma explícita, em vez de retornar o bucket compartilhado — então um comentário deletado pode aparecer como 490 ou 491 dependendo do que o Instagram retornar.Como a API não separa esses casos, sempre leia errorDetails: ele carrega a redação do próprio Instagram, que costuma ser específica sobre a causa.O código
489 é reservado e não é retornado atualmente. Ele está reservado para o caso “este comentário já tem uma resposta”, que o Instagram atualmente não expõe como um sinal distinto — esse caso reporta 491 hoje. Ele é listado aqui apenas para que o número não seja reutilizado.Uma conexão genuinamente expirada ou inválida não está nesse intervalo. Se a credencial do Instagram armazenada expirou, a linha de activity é
status: "auth_error" em vez de failed, e reconectar a conta é a correção adequada. Com exceção de 492 — uma permissão ausente, concedida ao reconectar a conta —, os códigos acima são condições em nível de comentário e nunca significam “revincular”.GET /automations/:id/activity retorna. O motivo do Instagram está em actionResults[].errorDetails:
details:
errorDetails ali carrega a mesma string que o envelope coloca em details.
Ação:
- 490, 491, 495 — condições por comentário. Elas não podem ser recuperadas para aquele comentário específico e nenhum retry ajudará; a automação funciona normalmente no próximo comentário novo. Leia
errorDetailspara o motivo declarado do Instagram. - 492 — reconecte a conta do Instagram, concedendo todas as permissões solicitadas. Essa é uma correção em nível de conta e, caso contrário, afetará todos os comentários.
- 493 — nenhuma ação necessária além de aguardar; o limite horário é redefinido sozinho. Não é reenviado automaticamente, portanto a DM daquele comentário não é enviada.
- 494 — má configuração interna, não uma condição do lado do cliente. Entre em contato com o suporte se recorrer.
Um status
sent não garante a entrega. Independentemente das falhas acima, uma private reply que o Instagram aceita (status: "sent") ainda pode ser descartada silenciosamente quando a configuração Message requests do Instagram do destinatário bloqueia estranhos — isso não gera código de erro algum. Consulte Automation DM Sent but Not Delivered.Erros de opções de thread e mídia
Estes códigos são retornados quando uma opção não pode ser aplicada à publicação — mais frequentemente em um Thread do X ou em um thread do Threads, onde as opções que você envia se aplicam ao thread inteiro.182— O vídeo não atende ao requisito de duração. O vídeo é mais curto que o mínimo da rede ou mais longo que o máximo dela. A resposta informa a duração real do vídeo junto com o mínimo e o máximo aplicados, então compare os três para confirmar qual limite você atingiu. No X, o intervalo padrão é de 0.5 a 140 segundos (2 minutos e 20 segundos); para publicar um vídeo mais longo, definalongVideo: true, o que eleva o máximo para 4 horas em uma conta aprovada pelo X para vídeo longo. Outras redes têm seus próprios limites — consulte as diretrizes de mídia da rede em que você está publicando.101— Parâmetros ausentes ou incorretos. No Threads, isso é retornado quandoallowCountriesé enviado de uma conta que a Meta não tornou elegível para restrições geográficas. Nenhuma parte da publicação ou do thread é publicada. VerifiqueisEligibleForGeoRestrictionsno endpoint /user antes de enviar a opção.111— O X rejeitou a publicação. Este é o código geral para uma falha do X que não tem um código mais específico, então leia odetailsna resposta — ele carrega a mensagem do próprio X e é o que informa a causa. Uma causa comum é uma opção que a conta não tem direito de usar, comosubscribersOnlysem X Subscriptions, oulongPostem uma publicação única sem X Premium; nesse caso, remova a opção ou verifique os direitos da conta. Falhas de conexão e outros erros do lado do X também aparecem como111, e nesses casos vale a pena tentar novamente em vez de alterar sua requisição.Observe quelongPostnão é uma causa de111em um thread — ali ele é ignorado com um aviso e o thread é publicado. Consulte Post longo.275— A publicação é longa demais para ser publicada como um thread. A divisão do texto produziu mais que o máximo de 30 publicações. Encurte o texto ou divida-o em threads separados. Adicionar suas próprias quebras de thread com\n\nnão ajudará aqui — cada quebra cria outra publicação, então isso pode empurrar a contagem ainda mais além do limite.
Uma opção que sua conta não pode usar faz a publicação inteira falhar em vez de ser ignorada. Em um
thread, isso significa que nenhuma parte do thread é publicada — as partes que já haviam saído são
excluídas para você. A exclusão é feita com melhor esforço: se a rede rejeitar uma exclusão, essa parte pode
permanecer publicada, então verifique o thread e remova o que tiver ficado para trás. Antes, algumas dessas opções
eram descartadas silenciosamente em threads e o thread era publicado sem elas.
Erros de Link Session
Os códigos 501 a 513 pertencem à vinculação social: criar um link com Criar uma Link Session e abrir um. Eles carregam"action": "link session". Outros códigos da série 500 nesta página não têm relação — 514 a 518 são de
áudio de Reels do Instagram.
Faça o match pelo
code numérico, não pelo texto da mensagem, que pode variar ou ser traduzido.
Quais destes a sua página pode ouvir. Com um origin definido, um popup de vinculação envia
eventos de conclusão de vinculação à sua página, e o 513 pode chegar
dessa forma como um connect:error. 501, 502 e 503 não podem: um link morto é recusado antes de a
página saber para onde enviar eventos, então seu usuário vê o motivo na tela e sua página ouve
connect:cancelled quando ele fecha a janela. Para distinguir esses três, faça polling em
Consultar uma Link Session. 504 a 510 são recusas do próprio
POST e nunca chegam como eventos, e 511 e 512 são levantados enquanto a rede
social está fazendo o callback, então eles aparecem lá em vez de na sua página.
Erros de BYO Key do X/Twitter
Os códigos de erro a seguir são específicos das operações de BYO (Bring Your Own) Key do X/Twitter: Código 272 - Falha ao verificar a identidade do BYO Twitter (HTTP 400) O Ayrshare não conseguiu confirmar sua identidade no X/Twitter usando suas consumer keys BYO e os tokens OAuth armazenados no momento da vinculação. O formato da resposta varia conforme a chamada que a acionou; ambas as formas mapeiam para os mesmos três subcasos abaixo. Verifique qual se aplica fazendo login em x.com com a conta proprietária do BYO Developer App. O caminho de publicação emite uma resposta mínima:details com a string de erro bruta do X:
details espelha a dica do lado do X e é o sinal único mais confiável para determinar qual subcaso se aplica.
Conta suspensa. Fazer login no x.com mostra um aviso de suspensão. Ação: entre em contato com o suporte do X. Revincular não restaurará o acesso até que o X reative a conta.
Conta bloqueada. Fazer login no x.com apresenta um desafio de desbloqueio (CAPTCHA, verificação por telefone etc.). Ação: conclua o desafio de desbloqueio no x.com e tente a requisição novamente. Não é necessário revincular.
Identidade ou chaves incompatíveis. Sua conta do X está em boa situação no x.com, mas suas consumer keys BYO pertencem a um X Developer App diferente dos tokens OAuth armazenados no momento da vinculação. Ação: revincule o X em Social Accounts e autorize com a mesma conta do X que é proprietária do BYO Developer App.
Código 364 — Rate limit do X (HTTP 429)
O X limitou uma requisição feita com suas BYO keys. Este é o código de rate limit compartilhado do Ayrshare, e agora ele também abrange o caminho de leitura de comentários do X: Get Comments o retorna quando o X aplica rate limit à leitura, enquanto antes era retornada uma lista de comentários vazia.
code: 416 quando a conta está sem créditos, portanto o 416 não se limita a publicar texto ou obter analytics. O upload falha antes de a publicação ser feita e não é repetido — nenhuma nova tentativa pode ter êxito até que a conta tenha créditos.
x-access-level: read, o que confirma que seu Access Token foi gerado com permissões somente leitura.
Ação: no X Developer Console, atualize as permissões do app para Read and write and Direct message e, em seguida, regenere seu Access Token em Keys and tokens. O novo token herdará as permissões atualizadas. Consulte o Guia de configuração da BYO Key do X para detalhes.
Código 419 - Credenciais BYO ausentes (HTTP 400)
Operações do X/Twitter exigem credenciais de API BYO nos headers da requisição. O Ayrshare retorna o código 419 quando ambos os headers estão ausentes e também quando apenas um do par está presente. A string message varia dependendo de qual header (ou headers) está ausente.
Quando X-Twitter-OAuth1-Api-Key e X-Twitter-OAuth1-Api-Secret estão ambos ausentes:
X-Twitter-OAuth1-Api-Key e X-Twitter-OAuth1-Api-Secret em todas as requisições destinadas ao X. Se você fornecer um sem o outro, a requisição será rejeitada com o mesmo código. Consulte a referência de headers das BYO Keys do X para a lista completa de headers.
Código 423 — OAuth legado do X/Twitter não é mais suportado (HTTP 403)
Retornado quando uma requisição do X/Twitter depende do caminho OAuth legado (não BYO), que não é mais suportado. O acesso à API do X agora exige suas próprias credenciais de X Developer App fornecidas via headers de requisição.
X-Twitter-OAuth1-Api-Key e X-Twitter-OAuth1-Api-Secret em todas as requisições destinadas ao X. Consulte o Guia de configuração da BYO Key do X para as etapas completas de configuração.
Erros de aprimoramento de legenda
Código 441 — Falha no aprimoramento de legenda (HTTP 502) Retornado quando um aprimoramento de legenda (por exemplo,shortenLinks) falha para uma ou mais plataformas durante a preparação de uma publicação. Cada plataforma afetada aparece no array errors com source: "handlePostAdditions" e code: 441.
Quando apenas algumas plataformas falham, as outras ainda publicam com sucesso e seus resultados aparecem em postIds. Nesse caso, o status de nível superior é "error", mas postIds não está vazio — os clientes devem tratar status e errors[] como complementares, e não mutuamente exclusivos.
code: 441 de nível superior com HTTP 502 e nenhuma publicação é criada:
- Se
postIdsnão estiver vazio (algumas plataformas publicaram com sucesso), não reenvie o conjunto completo de plataformas — isso duplicaria a publicação nas plataformas bem-sucedidas. Em vez disso, inspecioneerrors[]para identificar as plataformas que falharam e tente novamente com apenas essas plataformas, ou confie em seu próprio fluxo de retry idempotente. - Se
postIdsestiver vazio ou ausente (falha total no momento do agendamento/publicação), reenvie a requisição completa com segurança. - Se a falha persistir, envie a publicação sem a flag de aprimoramento (por exemplo, remova
shortenLinks) ou entre em contato com o suporte.
Erros de busca de mídia / acesso do crawler
Código 499 — Sondagem de mídia do Ayrshare temporariamente indisponível (HTTP 503) Retornado quando o Ayrshare não consegue concluir sua inspeção de mídia pré-publicação porque o serviço interno de sondagem de mídia não pôde ser contatado ou retornou uma resposta inválida. Trata-se de uma falha do serviço do Ayrshare, e não de evidência de que sua URL de mídia, CDN, regras de user-agent ou configuração derobots.txt estejam incorretas. O erro traz retryAvailable: true; tente novamente a plataforma que falhou em instantes. Se uma requisição multiplataforma teve sucesso parcial, tente novamente apenas as plataformas listadas em errors[] para evitar publicações duplicadas.
mediaUrls malformados, mídia que não pode ser lida e algumas falhas de upload/busca pela rede. Verifique primeiro qualquer details retornado. Para uma falha de acesso, confirme que a URL é publicamente acessível, permanece válida por tempo suficiente para a publicação e não bloqueia requisições remotas. /media/urlExists realiza apenas uma verificação de acessibilidade via HEAD; um resultado bem-sucedido ali não garante que a inspeção de mídia pré-publicação mais profunda ou o crawler de uma rede social consiga baixar e processar o arquivo. Quando a falha específica é que o próprio serviço de sondagem do Ayrshare está indisponível, você recebe o código 499 (com nova tentativa) em vez do código 164.
Código 440 — A rede social não conseguiu baixar a mídia (HTTP 400)
Retornado quando o crawler de publicação da plataforma não consegue baixar o mediaUrl que você forneceu — mais comumente porque o robots.txt ou uma regra de WAF / bot-fight está bloqueando o crawler (por exemplo, o facebookexternalhit da Meta). A string details vem da plataforma upstream e frequentemente é o texto do erro 2207052 da Meta/Instagram.
details normalmente contém "Restricted by robots.txt" ou "HTTP error code 403". O código 138 também é usado para problemas de proporção / formato e outros erros genéricos do Instagram, então a variante de busca de mídia é identificável pela string details.
mediaUrl. A API do Threads não retorna strings de detalhes, então o diagnóstico geralmente requer verificar a ocorrência simultânea de um 440 ou 138 do Instagram na mesma publicação.
robots.txt e um comando de verificação.
Mídia do Threads não está pronta
Código 522 — Mídia do Threads não está pronta para publicação (HTTP 400) O Threads não havia terminado de preparar a publicação quando o Ayrshare tentou publicá-la. O Threads pode informar que uma publicação está pronta alguns segundos antes de aceitar a publicação. O Ayrshare aguarda e tenta novamente por até 30 segundos no total para uma publicação do Threads, considerando todas as partes de uma thread com várias partes, antes de retornar este erro, então a maioria dessas publicações agora é publicada sem nenhum erro. Isso geralmente é temporário do lado do Threads e o seu conteúdo não é a causa. Comentários, respostas e primeiros comentários do Threads recebem a mesma espera (um primeiro comentário recebe seus próprios 30 segundos após a publicação ir ao ar), mas não retornam o código 522. Em uma thread com várias partes, o objetocode: 522 não fica diretamente em errors: ele é a última entrada do array posts do erro do Threads, e o status HTTP 400 acima se aplica apenas a uma publicação única do Threads. noAutoRetry: true apenas impede que o servidor MCP do Ayrshare tente novamente a publicação por conta própria; você ainda pode tentar novamente.
postIds primeiro. Se nada foi publicado, tente publicar novamente com o endpoint retry post. Se outra plataforma da mesma publicação já foi publicada, envie uma nova publicação apenas para o Threads: o retry post reenvia o payload original para todas as plataformas, o que publicaria novamente as que tiveram sucesso.
Threads com várias partes: um postIds vazio não prova que nenhuma parte da thread esteja no ar. O Ayrshare remove as partes que foram publicadas quando uma parte posterior falha, mas, se uma remoção falhar, essa parte permanece no Threads. Antes de tentar novamente uma thread com várias partes, verifique a conta do Threads e exclua as partes que ainda estiverem lá; caso contrário, a nova tentativa as publicará novamente.
Limite de taxa das análises do Facebook
Código 444 — Limite de taxa de análises da Página do Facebook (HTTP 429) Retornado quando uma Página do Facebook excedeu o limite de taxa por Página da Meta no endpoint de análises. O erro subjacente da Meta é80001 (“There have been too many calls to this Page account.”). A Página permanece vinculada e a publicação continua funcionando — apenas o fan-out de análises para essa Página é limitado.
Quando o throttle é detectado para uma única publicação em uma resposta de /history/facebook ou análises, cada publicação afetada carrega code: 444 em facebook.code com errCode: 80001:
Verificação de identidade da Meta
Código 326 — Verificação de identidade da Meta obrigatória (HTTP 403) Retornado quando a Meta exige verificação adicional de identidade para a conta conectada antes de aceitar a requisição. Isso se aplica a todas as plataformas da Meta — Facebook, Instagram, Facebook Groups, Threads e Messenger. Reconectar a conta não resolve isso; a verificação deve ser concluída do lado da Meta.Bloqueio por Padrões da Comunidade do Facebook
Código 249 — Bloqueio por Padrões da Comunidade do Facebook (HTTP 400) Retornado quando o Facebook bloqueia uma publicação com base nos seus Padrões da Comunidade. O bloqueio pode estar na conta ou na Página do Facebook, ou na própria publicação. O Facebook usa o mesmo erro subjacente para os dois casos e não informa qual deles se aplica. Na prática, o bloqueio costuma ser aplicado à conta ou à Página, então reescrever ou reenviar o conteúdo muitas vezes não resolve. Assim como a Restrição de conta do Facebook (código 476), esse é um resultado de fiscalização do lado da Meta: é não passível de retry e não carrega a flagretryAvailable. Na primeira violação, a conta permanece vinculada ao Ayrshare e nenhuma revinculação é necessária; revincular não remove o bloqueio. Uma violação reincidente é diferente; veja abaixo.
O Facebook não retorna o motivo específico pela API, então o cliente deve verificar a página Account Status do Facebook diretamente para ver o motivo e recorrer. Quando o Facebook fornece seu próprio texto literal, o Ayrshare o exibe no campo details. O Ayrshare também envia um e-mail de notificação ao proprietário da conta quando o bloqueio é detectado.
Uma violação reincidente dos Padrões da Comunidade no mesmo User Profile desvincula a conta do Facebook do Ayrshare e suspende o User Profile.
code, 249, e não pelo texto de message. A redação de message pode ser refinada com o tempo, enquanto o código é estável.
Ação: faça login no Facebook, clique na sua foto de perfil (canto superior direito), abra a seção Help e selecione Account Status. O assistente de suporte do Facebook ali informa o motivo específico (que a API não retorna) e permite recorrer. Não oriente o usuário a revincular a conta, pois revincular não remove um bloqueio em nível de conta ou de Página. Consulte Conta do Facebook ou Instagram restrita para o guia completo de solução de problemas.
Restrição de conta do Facebook
Código 476 — Restrição de conta do Facebook (HTTP 400) Retornado quando uma publicação no Facebook falha porque a Meta aplicou uma restrição à conta (subcódigos de erro da Meta2424009 e 1404078, ou a redação de restrição da Meta quando o erro não carrega subcódigo). Essa é uma restrição em nível de conta, não uma falha de publicação transitória — é não passível de retry e não carrega a flag retryAvailable. Reenviar a mesma publicação não terá sucesso até que a restrição seja resolvida com a Meta. A conta permanece vinculada ao Ayrshare; nenhuma revinculação é necessária.
A Meta não retorna o motivo específico da restrição pela API, então o cliente deve verificar a página Account Status da Meta diretamente para ver o motivo e recorrer. Quando a Meta fornece seu próprio texto literal, o Ayrshare o exibe no campo details. O Ayrshare também envia um e-mail de notificação ao proprietário da conta quando a restrição é detectada.
Erros de conversão de formato de imagem
O Ayrshare converte automaticamente imagens WebP, HEIC, HEIF e AVIF para JPEG antes de publicar em plataformas que não as aceitam (Instagram, LinkedIn, TikTok, Google My Business, Threads e Snapchat para WebP; todas as plataformas para HEIC, HEIF e AVIF). A conversão ocorre de forma transparente no momento do envio. Os três erros abaixo são disparados apenas quando o próprio pipeline de conversão não consegue ser concluído; se a imagem de origem já estiver em um formato suportado, nenhuma conversão é tentada e esses códigos não aparecerão. Código 450 — Falha na conversão de formato de imagem (HTTP 400) A imagem foi baixada, mas não pôde ser recodificada como JPEG. As causas mais comuns são um arquivo de origem corrompido, um formato interno inesperado dentro do container ou uma imagem que excede o limite de tamanho de conversão.mediaUrl de origem diretamente em um navegador para confirmar que ele é renderizado. Se sim, reexporte a imagem para um JPEG ou PNG limpo e tente publicar novamente.
Código 451 — Falha ao baixar imagem para conversão (HTTP 400)
O pipeline de conversão não conseguiu buscar a imagem de origem. Causas típicas incluem uma resposta 4xx/5xx do origin, um timeout de rede, uma cadeia de redirecionamentos que excede o limite de saltos ou uma URL que resolve para um endereço não público (bloqueado pelo guard de SSRF). O campo details, quando presente, carrega a string da causa subjacente.
mediaUrl é publicamente acessível (sem autenticação, sem bloqueios de robots.txt, resolve por HTTPS). Se a URL redirecionar, garanta que o destino final também seja público e não esteja em uma rede privada.
Código 452 — Falha no upload da imagem convertida (HTTP 500)
A conversão foi bem-sucedida, mas o Ayrshare não conseguiu preparar o JPEG convertido em seu bucket de armazenamento temporário. Essa é uma falha interna do lado do Ayrshare e é passível de retry.
mediaUrl e o timestamp aproximado.
Erros transitórios de upload no YouTube
Os códigos de erro a seguir fornecem sinais específicos para falhas de upload no YouTube que normalmente são transitórias e seguras para retry. Ambas as respostas incluemretryAvailable: true, então as integrações podem se ramificar com base nesse booleano em vez do status code HTTP.
A maioria das respostas anteriores de code: 176 para uploads do YouTube agora são roteadas para 453 (timeout transitório) ou 454 (serviço temporariamente indisponível), ambas com retryAvailable: true. Se sua integração filtra HTTP 500 para tentar novamente uploads do YouTube, mude para filtrar pelo campo retryAvailable no corpo da resposta.
Código 453 — Upload do YouTube expirou (HTTP 504)
Retornado quando o pipeline de ingestão do YouTube do Google expirou ao aceitar o upload. Isso é normalmente transitório e se resolve por conta própria dentro de um ou dois minutos.
retryAvailable no corpo da resposta, em vez do status HTTP, para detectar falhas passíveis de retry. Você pode usar o endpoint retry post para reenviar o mesmo payload.
Código 454 — Serviço de upload do YouTube temporariamente indisponível (HTTP 503)
Retornado quando o endpoint de upload do YouTube retorna um status 5xx ou quando a conexão com o YouTube foi resetada ou expirou na camada de socket (ECONNRESET, ETIMEDOUT, ESOCKETTIMEDOUT). Essas condições são transitórias.
retryAvailable no corpo da resposta, em vez do status HTTP, para detectar falhas passíveis de retry.
Erros de thumbnail do YouTube — Código 307
O código307 é retornado quando um thumbNail personalizado do YouTube não pode ser aplicado. Quando o próprio vídeo é publicado com sucesso, isso não faz a publicação falhar — o resultado do YouTube mantém status: "success" e expõe a falha adicionalmente em um array warnings (feature: "thumbnail", code: 307). O subobjeto legado thumbnail é mantido para compatibilidade retroativa.
A causa mais comum é um canal do YouTube não verificado. Quando um canal não concluiu a verificação por telefone, o YouTube retorna um 403 upstream com a mensagem genérica "The authenticated user doesn't have permissions to upload and set custom video thumbnails". Essa redação soa como um problema de OAuth, mas, na prática, quase sempre é um problema de verificação, então verifique o canal primeiro. Revincular a conta do YouTube é uma causa secundária.
warnings (o status de nível superior permanece "success"). Isso vale independentemente de quando o problema for detectado:
- Detectado antes do upload. Quando a validação pré-publicação pode determinar definitivamente que o thumbnail é inválido (tipo de arquivo errado, tamanho confirmado acima de 2MB ou URL inacessível), o Ayrshare ignora o thumbnail, publica o vídeo mesmo assim e informa o motivo preciso em
warnings— evitando uma tentativa de upload fadada ao fracasso e oferecendo uma mensagem mais clara do que a que o provedor retornaria. - Detectado após o upload. Quando a falha só é detectável depois que o YouTube processa a requisição (por exemplo, o
403de canal não verificado ou um413para uma imagem grande demais), o vídeo já está no ar e a falha é exposta no mesmo arraywarnings.
status: "success" + warnings mostrado anteriormente nesta seção.
Ação: verifique seu canal do YouTube em https://www.youtube.com/verify (verificação por telefone). Se seu canal já estiver verificado e os thumbnails ainda falharem, desvincule e revincule sua conta do YouTube em Social Accounts e conceda todas as permissões. Consulte YouTube Thumbnail Not Applied (Unverified Channel) para o guia completo de solução de problemas.
Erros de autorização do Google Business Profile
Código 519 — Serviço de autorização do Google Business Profile temporariamente indisponível (HTTP 503) Retornado quando o Ayrshare não conseguiu concluir o refresh do token de autorização do Google, porque o endpoint de token do Google demorou para responder ou retornou uma falha transitória. O refresh é repetido automaticamente antes que esse código seja retornado, e a resposta incluiretryAvailable: true, então as integrações podem se ramificar com base nesse booleano em vez do status code HTTP. A conta permanece conectada — trata-se de uma condição temporária no serviço de autorização do Google, não de uma conexão quebrada.
Toda operação do Google Business Profile atualiza a autorização primeiro, então qualquer uma delas pode retornar esse código — publicar uma publicação, ler o histórico de publicações, atualizar dados de localização, buscar a conta conectada, listar avaliações e responder a uma avaliação.
A maioria das respostas anteriores de code: 227 nesses caminhos agora é roteada para 519 com retryAvailable: true. O código 227 pede que o usuário reconecte a conta, o que nunca resolveu uma falha transitória de refresh — a autorização em si permaneceu intacta o tempo todo. Se sua integração filtra por 227 para solicitar a revinculação do Google Business Profile, mude para ramificar com base no campo retryAvailable no corpo da resposta e tentar novamente com backoff.
details traz o motivo informado pelo Google ou — quando o refresh expirou localmente sem corpo de resposta do Google — um resumo das tentativas feitas e do tempo decorrido.
Ação: tente novamente a requisição com backoff exponencial. Ramifique com base no campo retryAvailable no corpo da resposta, em vez do status HTTP, para detectar falhas passíveis de retry.
Aviso de divulgação de IA do Pinterest
Código 521 — Divulgações de IA do Pinterest não aplicadas (HTTP 200) Aviso, não erro. Retornado quandopinterestOptions.aiDisclosures é inválido, por exemplo um valor desconhecido ou com maiúsculas/minúsculas incorretas. Pela REST API, um valor que não seja um array de strings também retorna 521. O Pin ainda é publicado, mas o Ayrshare não envia nenhuma divulgação de IA ao Pinterest. O servidor MCP e a API GraphQL verificam primeiro os tipos dos valores, então valores malformados, como uma lista contendo um número, são rejeitados nessas interfaces antes da publicação. O aviso chega em postIds[].warnings[] da entrada do Pinterest, não em errors[], e traz feature: "pinterestOptions.aiDisclosures". Os valores aceitos são AI_MODIFIED e SYNTHETIC_PERFORMER.
Erros de publicação no Reddit
Código 442 — Banido no subreddit do Reddit (HTTP 400) Retornado quando a conta foi banida de publicar no subreddit de destino. Isso não é passível de retry — a publicação não terá sucesso se for reenviada como está. A mensagem inclui o nome do subreddit afetado (por exemplo,r/news).
r/news).
Erros de moderação
Código 438 — Entrada de moderação rejeitada (HTTP 400) Retornado porPOST /validate/moderation quando o provedor de IA rejeita a entrada fornecida — por exemplo, um tipo de arquivo não suportado. Trata-se de um problema de entrada na requisição, não de uma falha transitória de processamento.
Contraste o código 438 com o código 331. O código 331 cobre o mesmo cenário de moderação, mas representa uma falha genuína de processamento do lado do provedor (HTTP 500, mensagem “There was an issue with the AI processing. Please try again.”). O código 331 é uma falha transitória do lado do servidor que você pode tentar novamente, enquanto o código 438 indica que a própria entrada foi rejeitada e deve ser corrigida antes de nova tentativa.
Erros de atualização de autorização do LinkedIn
Código 524 — Atualização do token do LinkedIn rejeitada (HTTP 500) Retornado quando o LinkedIn se recusa a atualizar a autorização devido a um problema na configuração do LinkedIn do aplicativo, e não na conta do usuário. A conexão do LinkedIn do usuário continua válida, então revincular não resolve. A resposta não inclui um camporesolution.relink e traz retryAvailable: false, porque tentar novamente não resolve.
Qualquer operação do LinkedIn que atualize a autorização primeiro pode retornar este código, como publicar um post depois que o token de acesso expirou.
Se o LinkedIn continuar falhando na atualização por um motivo temporário, a Ayrshare tenta novamente e depois retorna o código 119 (“There was an issue connecting with LinkedIn. Please try again.”) em vez disso. É seguro tentar novamente mais tarde no caso do código 119; o código 524 não é resolvido com novas tentativas.
Erros de análises do LinkedIn
Código 475 — Revincule o perfil do LinkedIn para análises (HTTP 403) Retornado porPOST /analytics/post e POST /analytics/social para um perfil pessoal (member) do LinkedIn vinculado antes de as análises de member serem lançadas. Esses perfis não têm os escopos de member analytics do LinkedIn (r_member_postAnalytics, r_member_profileAnalytics), então o LinkedIn rejeita a requisição de análises. A publicação não é afetada.
475 por até ~5-10 minutos antes de as análises serem bem-sucedidas.
Erros de comentários do TikTok
Código 288 — Comentário do TikTok adiado / publicação ainda em processamento (HTTP 400) O TikTok processa vídeos de forma assíncrona, então oid de uma publicação recém-lançada é "pending" até que o webhook post.publish.publicly_available do TikTok resolva o id real do vídeo. Uma requisição de get-comments, comentário ou resposta para uma publicação que ainda está sendo processada (ou cujo id seja "failed") é recusada antes de qualquer chamada ao TikTok e retorna o código 288 em vez de uma falha genérica.
tikTokPublished ou consulte /history até que o id da publicação seja o id numérico do vídeo resolvido. Um first comment é publicado automaticamente assim que a publicação é resolvida, então não é necessário tentar novamente. Para uma publicação "failed", a mensagem informa que o vídeo não foi publicado e que a ação não será executada.
Erros de Story Expirados ou Indisponíveis
Código 485 — Comentários de Story do Instagram / Facebook e Análises de Story do Instagram (HTTP 404 quando representativo) Stories podem se tornar expirados ou indisponíveis após sua janela de disponibilidade. Após essa janela, comentários ou insights não podem ser obtidos. O código485 identifica:
- etapas de Story do Instagram e do Facebook expiradas ou indisponíveis em get-comments; e
- uma etapa de Story do Instagram expirada ou indisponível em
POST /analytics/post.
485. Os clientes devem fazer match pelo code numérico, não pelo texto exato da mensagem, que pode variar ou ser traduzido.
Em uma leitura multiplataforma em que pelo menos uma outra plataforma é bem-sucedida, a etapa que falhou aparece no array errors[] de nível superior enquanto as plataformas saudáveis retornam normalmente. A resposta geral é HTTP 200 com status: "partial" de nível superior (consulte Leituras Multiplataforma & Sucesso Parcial para comentários e análises).
Exemplo de Sucesso Parcial em Get Comments
Exemplo de Sucesso Parcial em Post Analytics
status: "error" de nível superior e inclui o array errors[] completo. O código representativo 485 mapeia para HTTP 404; outros códigos representativos usam seus próprios mapeamentos HTTP.
Ação: trate o código 485 como um sinal de que os comentários ou insights de Story solicitados não podem ser obtidos. Faça match pelo código em vez de tirar conclusões de falha permanente, capacidade de retry ou vínculo de conta a partir do texto da mensagem.
Tradução da mensagem de erro
A mensagem de erro da resposta da API pode ser traduzida automaticamente para o idioma de sua escolha. Isso é útil se você quiser exibir o erro diretamente ao usuário no idioma de preferência dele. Veja aqui se você deseja escolher o idioma da página de vinculação social. No header, inclua:Language_Code é um dos códigos de idioma disponíveis.
Por exemplo, o seguinte traduzirá o erro para francês.