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:
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, a resposta também define relink: true e retryAvailable: true, e a mensagem instrui o usuário a desvincular e revincular a conta do Instagram, concedendo todas as permissões:
2207085, oriente o usuário a desvincular e revincular a conta do Instagram em Social Accounts, concedendo todas as permissões solicitadas, e depois tente publicar novamente. 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 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 416 — Créditos do X esgotados (HTTP 402)
Sua conta de desenvolvedor do X não tem créditos de API carregados. Todas as chamadas da API do X exigem 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 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 omediaUrl 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.
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.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 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 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. Você pode usar o endpoint retry post para reenviar o mesmo payload.
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 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 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.
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.
