> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de erro do Ayrshare

> Códigos de erro específicos retornados pelo Ayrshare.

A REST API incluirá uma resposta com uma lista de erros, quando aplicável.

<Info>
  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](/errors/errors-http) para detalhes.
</Info>

Cada chamada de API pode retornar erros diferentes dependendo da requisição específica e de eventuais problemas encontrados na rede social.
A resposta de erro conterá detalhes sobre o que deu errado durante a chamada da API.

Por exemplo, uma publicação considerada duplicada pelo Twitter e Facebook retornaria a seguinte resposta.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 110,
      "message": "Status is a duplicate.",
      "post": "Today is a great day",
      "platform": "twitter"
    },
    {
      "action": "post",
      "status": "error",
      "code": 107,
      "message": "Facebook Error: This status update is identical to the last one you posted.
        Try posting something different, or delete your previous update.",
      "platform": "facebook"
    }
  ],
  "postIds": [],
  "id": "6APU4qqI7XO7JM3BOy6B"
}
```

Observe:

<ul class="custom-bullets">
  <li>
    O campo `errors` contém o array de erros, um por rede social que teve um erro.
  </li>

  <li>O `action` refere-se ao tipo de erro retornado.</li>

  <li>
    O campo `status` de 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 campo `status` será "success"; caso contrário,
    o campo status será "error".
  </li>

  <li>O campo `code` contém o código de erro de referência do Ayrshare.</li>
  <li>O campo `message` traz os detalhes específicos do erro.</li>
</ul>

### Tratando erros

Você deve tratar todas as respostas de erro e tomar a ação apropriada. Ocorreu um erro se:

<ul class="custom-bullets">
  <li>O código de retorno da resposta não é `200`</li>
  <li>O status da resposta JSON é `error`</li>
</ul>

Por exemplo, se o vínculo do Facebook foi removido pelo seu usuário — ele alterou a senha ou removeu o acesso do Ayrshare — a seguinte resposta ocorreria ao publicar, com um código de resposta `400 Bad Request`.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 161,
      "message": "Facebook authorization error. This can occur if your Facebook security changes. Try unlinking and re-linking Facebook or contact us for assistance.",
      "platform": "facebook"
    }
  ],
  "postIds": [],
  "id": "gh7SyTpeD2CQAMxWk3oh",
  "post": "A great Facebook Posts"
}
```

Uma ação pode ser notificar seu usuário por meio do seu painel, SMS ou e-mail.

Outro exemplo é quando a imagem publicada no Instagram tem dimensões ou proporção erradas, com um código de resposta `400 Bad Request`:

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 138,
      "message": "Instagram Error: There was an issue posting to Instagram. The submitted image with aspect ratio ('1440/2158',) cannot be published. Please submit an image with a valid aspect ratio.",
      "platform": "instagram"
    }
  ],
  "postIds": [],
  "id": "Jxe2nMM3FmEvMXFSY3g4",
  "post": "Is this a good image?"
}
```

Uma ação pode ser reenviar as imagens com a proporção correta.

### 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](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/content_publishing_limit/) 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 exibe `code: 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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "rate limit",
      "status": "error",
      "code": 435,
      "message": "Instagram rate limit reached. Please wait before retrying your post.",
      "details": "Retry-After: 3600",
      "platform": "instagram"
    }
  ]
}
```

**Ação:** aguarde a janela do limite de taxa ser redefinida antes de tentar novamente. Quando a Meta fornece um header `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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 436,
      "message": "Instagram media processing timed out. Please try posting again.",
      "retryAvailable": true,
      "platform": "instagram"
    }
  ]
}
```

**Ação:** tente publicar novamente usando o endpoint [retry post](/apis/post/retry-post). Se o problema persistir, tente reduzir o tamanho do arquivo de mídia.

**Código 447 — Trial Reels do Instagram: graduationStrategy ausente (HTTP 400)**

Retornado quando `instagramOptions.trialParams` é fornecido em uma requisição [`/post`](/apis/post/post), mas `graduationStrategy` está ausente, `null` ou é uma string vazia. Trial reels exigem uma estratégia de graduação explícita — consulte [Trial Reels](/apis/post/social-networks/instagram#trial-reels).

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 447,
      "message": "Instagram trial reels require instagramOptions.trialParams.graduationStrategy (\"MANUAL\" or \"SS_PERFORMANCE\").",
      "platform": "instagram"
    }
  ]
}
```

**Ação:** defina `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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 448,
      "message": "Invalid Instagram graduationStrategy. Must be \"MANUAL\" or \"SS_PERFORMANCE\".",
      "details": "Received: manual",
      "platform": "instagram"
    }
  ]
}
```

**Ação:** envie `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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 449,
      "message": "Instagram trial reels must be a single video (.mp4 or .mov) — carousels and stories are not supported.",
      "details": "Carousels are not supported.",
      "platform": "instagram"
    }
  ]
}
```

**Ação:** envie uma única URL de vídeo `.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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 258,
      "message": "Error with Instagram.",
      "platform": "instagram"
    }
  ]
}
```

Quando 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:

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 258,
      "message": "Error with Instagram. Please unlink and relink your Instagram account, granting all permissions, then retry.",
      "relink": true,
      "retryAvailable": true,
      "platform": "instagram"
    }
  ]
}
```

**Ação:** para o subcaso `2207085`, oriente o usuário a desvincular e revincular a conta do Instagram em [Social Accounts](https://app.ayrshare.com/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 campo `retryAvailable` será `true`.

```json theme={"system"}
{
  "retryAvailable": true
}
```

Você pode então tentar a chamada novamente com o mesmo payload.
Se for uma publicação, você pode usar o endpoint [retry post](/apis/post/retry-post).

### 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](https://x.com) com a conta proprietária do BYO Developer App.

O caminho de publicação emite uma resposta mínima:

```json theme={"system"}
{
  "status": "error",
  "code": 272,
  "message": "Failed to verify BYO Twitter identity",
  "platform": "twitter"
}
```

O caminho de análises emite uma mensagem mais longa e autoexplicativa e pode incluir um campo `details` com a string de erro bruta do X:

```json theme={"system"}
{
  "action": "post",
  "status": "error",
  "code": 272,
  "message": "There is an issue authorizing your X/Twitter account. Login to x.com to verify your account status and then try unlinking Twitter and relinking on the social accounts page.",
  "resolution": {
    "relink": true,
    "platform": "twitter"
  },
  "details": "The user used for authentication is suspended"
}
```

Quando presente, `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.

```json theme={"system"}
{
  "status": "error",
  "code": 416,
  "message": "Your enrolled account does not have any credits to fulfill this request. Purchase credits at console.x.com.",
  "platform": "twitter"
}
```

**Ação:** acesse [console.x.com](https://console.x.com) → Billing → Credits e compre créditos. Mesmo \$5 são suficientes para centenas de chamadas de API.

**Código 417 — Permissões do app OAuth 1.0a (HTTP 403)**

Seu Access Token do X não tem as permissões corretas para a operação solicitada.

```json theme={"system"}
{
  "status": "error",
  "code": 417,
  "message": "Your client app is not configured with the appropriate oauth1 app permissions. Set app to 'Read and write and Direct message', then regenerate your Access Token.",
  "platform": "twitter"
}
```

Você também pode ver o header de resposta `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](/dashboard/connect-social-accounts/x-twitter-byo-keys#troubleshooting) 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:

```json theme={"system"}
{
  "action": "x_credentials_required",
  "status": "error",
  "code": 419,
  "message": "X/Twitter operations require your own API credentials. Missing: X-Twitter-OAuth1-Api-Key, X-Twitter-OAuth1-Api-Secret. Please provide your X Developer App credentials in the request headers. See https://docs.ayrshare.com/x-api-setup for setup instructions.",
  "resolution": {
    "docs": "https://docs.ayrshare.com/x-api-setup"
  },
  "platform": "twitter"
}
```

Quando apenas um do par está presente (por exemplo, a chave sem o secret):

```json theme={"system"}
{
  "action": "x_credentials_required",
  "status": "error",
  "code": 419,
  "message": "You provided X-Twitter-OAuth1-Api-Key but not X-Twitter-OAuth1-Api-Secret. OAuth 1.0a requires both. Missing: X-Twitter-OAuth1-Api-Secret. See https://docs.ayrshare.com/x-api-setup for setup instructions.",
  "resolution": {
    "docs": "https://docs.ayrshare.com/x-api-setup"
  },
  "platform": "twitter"
}
```

**Ação:** envie `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](/dashboard/connect-social-accounts/x-twitter-byo-keys#header-reference) 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.

```json theme={"system"}
{
  "status": "error",
  "code": 423,
  "message": "X (Twitter) API access now requires your own API credentials. Include X-Twitter-OAuth1-Api-Key and X-Twitter-OAuth1-Api-Secret headers in your request. Setup guide: https://docs.ayrshare.com/dashboard/connect-social-accounts/x-twitter-byo-keys",
  "platform": "twitter"
}
```

**Ação:** configure um X Developer App e envie os headers `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](/dashboard/connect-social-accounts/x-twitter-byo-keys) 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`](/apis/post/post)) 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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "platform": "twitter",
      "status": "error",
      "source": "handlePostAdditions",
      "code": 441,
      "message": "Caption enhancement failed for twitter. <underlying error>. Post was not sent to this platform."
    }
  ],
  "postIds": [
    {
      "status": "success",
      "id": "...",
      "postUrl": "...",
      "platform": "bluesky"
    }
  ],
  "id": "..."
}
```

Se **todas** as plataformas falharem no aprimoramento, a resposta é um `code: 441` de nível superior com HTTP `502` e nenhuma publicação é criada:

```json theme={"system"}
{
  "status": "error",
  "action": "post",
  "code": 441,
  "message": "Caption enhancement failed. See error details for affected platforms.",
  "errors": [
    {
      "platform": "twitter",
      "status": "error",
      "source": "handlePostAdditions",
      "code": 441,
      "message": "Caption enhancement failed for twitter. <underlying error>"
    }
  ]
}
```

**Ação:** falhas de aprimoramento de legenda são normalmente transitórias (o encurtador ou serviço de aprimoramento subjacente retornou um erro).

* **Se `postIds` nã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, inspecione `errors[]` para identificar as plataformas que falharam e tente novamente com apenas essas plataformas, ou confie em seu próprio fluxo de retry idempotente.
* **Se `postIds` estiver 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 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.

```json theme={"system"}
{
  "status": "error",
  "errors": [{
    "action": "post",
    "code": 440,
    "message": "The social network could not download media from this URL (for example Instagram/Meta error 2207052). Ensure the file is publicly reachable by the platform's crawlers (e.g. facebookexternalhit), via media bucket's robots.txt file, not only in a browser.",
    "details": "Media download has failed.: The media could not be fetched from the provided URI...",
    "platform": "instagram",
    "status": "error"
  }],
  "postIds": [],
  "id": "..."
}
```

**Código 138 — Busca de mídia do Instagram bloqueada (HTTP 400)**

Código de fallback para falhas de busca de mídia do Instagram quando a resposta upstream é menos específica do que aquela que aciona o código 440. A string `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`.

```json theme={"system"}
{
  "status": "error",
  "errors": [{
    "retryAvailable": true,
    "status": "error",
    "code": 138,
    "details": "Media download has failed.: The media could not be fetched from the provided URI. Video download failed with: HTTP error code 403. Restricted by robots.txt",
    "action": "post",
    "platform": "instagram",
    "message": "Instagram Error: Instagram cannot process your post at this time. Please try your post again."
  }],
  "postIds": [],
  "id": "..."
}
```

**Código 379 — Erro de publicação no Threads**

Retornado quando a publicação no Threads falha. Mais comumente causado pelo mesmo problema de busca de mídia que os códigos 440 / 138 ao publicar em ambas as plataformas com o mesmo `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.

```json theme={"system"}
{
  "status": "error",
  "errors": [{
    "status": "error",
    "code": 379,
    "message": "Error posting to Threads.",
    "action": "post",
    "platform": "threads"
  }],
  "postIds": [],
  "id": "..."
}
```

**Ação:** consulte [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) para a solução de problemas completa, incluindo trechos de `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`](/apis/history/history-platform) ou [análises](/apis/analytics/social), cada publicação afetada carrega `code: 444` em `facebook.code` com `errCode: 80001`:

```json theme={"system"}
{
  "status": "error",
  "facebook": {
    "action": "rate limit",
    "status": "error",
    "code": 444,
    "errCode": 80001,
    "message": "Facebook Page has hit its per-Page rate limit on the analytics endpoint. Please wait a few minutes and retry.",
    "pageId": "...",
    "id": "..."
  },
  "httpErrorCode": 444,
  "lastUpdated": "...",
  "nextUpdate": "..."
}
```

**Ação:** aguarde alguns minutos e tente novamente. A janela de limite de taxa por Página da Meta normalmente é resolvida em uma hora, sem nenhuma ação na Página. **Não** oriente o usuário a revincular a conta — trata-se de um throttle transitório do lado da Meta, não de uma falha de autorização.

<Warning>
  Se você anteriormente tratava essa condição como `code: 161` ("Facebook authorization error … unlink and re-link"), atualize sua integração para reconhecer `code: 444` e tentar novamente com backoff em vez de iniciar um fluxo de revinculação. A classificação como `161` foi corrigida em abril de 2026.
</Warning>

### 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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 326,
      "message": "Meta is requesting additional identity verification for this account. Complete it at https://www.facebook.com/business-support-home and then retry. Reconnecting the account will not resolve this.",
      "platform": "facebook"
    }
  ]
}
```

**Ação:** peça ao proprietário da conta que conclua a verificação de identidade da Meta no [Meta Business Support](https://www.facebook.com/business-support-home) e depois tente a requisição novamente. **Não** oriente o usuário a revincular a conta — revincular não removerá essa exigência.

### 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 Meta `2424009` 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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 476,
      "message": "There is a Facebook restriction on your account. Log in to Facebook, click your profile picture (top-right), open the Help section and select Account Status. Meta's support assistant there surfaces the specific restriction reason (which the API doesn't return) and lets you appeal.",
      "details": "...",
      "platform": "facebook"
    }
  ]
}
```

**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 da Meta ali informa o motivo específico da restrição e permite recorrer. Como a restrição é aplicada pela Meta em nível de conta, esse código é não passível de retry — não construa lógica de retry automático em torno dele; resolva a restrição com a Meta primeiro.

### 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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "image conversion",
      "status": "error",
      "code": 450,
      "message": "The image format could not be converted. The source image may be corrupt or inaccessible. Please verify the media URL and try again.",
      "platform": "instagram"
    }
  ]
}
```

**Ação:** abra 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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "image conversion",
      "status": "error",
      "code": 451,
      "message": "The image could not be downloaded for format conversion.",
      "details": "HTTP 403 from origin",
      "platform": "linkedin"
    }
  ]
}
```

**Ação:** confirme que o `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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "image conversion",
      "status": "error",
      "code": 452,
      "message": "An error occurred uploading the converted image. Please try again.",
      "platform": "tiktok"
    }
  ]
}
```

**Ação:** tente publicar novamente. Se o erro persistir em várias tentativas, entre em contato com o suporte informando o `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 incluem `retryAvailable: 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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 453,
      "message": "YouTube upload timed out (Google ingest). This is typically transient; please retry in 1–2 minutes.",
      "retryAvailable": true,
      "platform": "youtube"
    }
  ]
}
```

**Ação:** tente publicar novamente após 1–2 minutos 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. Você pode usar o endpoint [retry post](/apis/post/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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 454,
      "message": "YouTube upload service temporarily unavailable. Please retry.",
      "retryAvailable": true,
      "platform": "youtube"
    }
  ]
}
```

**Ação:** tente publicar novamente 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. Você pode usar o endpoint [retry post](/apis/post/retry-post) para reenviar o mesmo payload.

### Erros de thumbnail do YouTube — Código 307

O código `307` é 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.

```json theme={"system"}
{
  "status": "success",
  "id": "<videoId>",
  "thumbnail": {
    "action": "post",
    "status": "error",
    "code": 307,
    "message": "Your YouTube channel must be verified to set a custom thumbnail. Verify your channel at https://www.youtube.com/verify (phone verification). If your channel is already verified, try unlinking and re-linking your YouTube account to restore permissions.",
    "details": "<upstream message>"
  },
  "warnings": [
    {
      "feature": "thumbnail",
      "code": 307,
      "message": "Your YouTube channel must be verified to set a custom thumbnail. Verify your channel at https://www.youtube.com/verify (phone verification). If your channel is already verified, try unlinking and re-linking your YouTube account to restore permissions.",
      "details": "<upstream message>"
    }
  ]
}
```

O Ayrshare também valida o thumbnail antes de publicar sempre que possível: o arquivo deve ser um **PNG ou JPG/JPEG**, ter **2MB ou menos** e ser servido a partir de uma **URL acessível**.

Um problema com thumbnail **nunca faz a publicação falhar** — o vídeo sempre é publicado e a falha sempre é exposta como uma entrada não fatal em `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 `403` de canal não verificado ou um `413` para uma imagem grande demais), o vídeo já está no ar e a falha é exposta no mesmo array `warnings`.

De qualquer forma, a resposta se parece com o exemplo `status: "success"` + `warnings` mostrado anteriormente nesta seção.

**Ação:** verifique seu canal do YouTube em [https://www.youtube.com/verify](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](https://app.ayrshare.com/social-accounts) e conceda todas as permissões. Consulte [YouTube Thumbnail Not Applied (Unverified Channel)](/help-center/technical-support/youtube_thumbnail_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`).

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 442,
      "message": "You've been banned from posting to r/news. This post will not succeed on retry — remove it from your target subreddits.",
      "platform": "reddit"
    }
  ]
}
```

**Ação:** remova o subreddit banido dos seus subreddits de destino. Reenviar a publicação sem alterações não terá sucesso.

**Código 443 — Palavra proibida no título do Reddit (HTTP 400)**

Retornado quando um subreddit rejeita a publicação porque o título contém uma palavra proibida. Edite o título antes de tentar novamente — reenviar como está não terá sucesso. A mensagem inclui o nome do subreddit afetado (por exemplo, `r/news`).

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 443,
      "message": "r/news rejected this post because the title contains a disallowed word. Edit the title before retrying — retrying as-is will not succeed.",
      "platform": "reddit"
    }
  ]
}
```

**Ação:** edite o título da publicação para remover a palavra proibida e tente novamente.

### Erros de moderação

**Código 438 — Entrada de moderação rejeitada (HTTP 400)**

Retornado por [`POST /validate/moderation`](/apis/post/post) 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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "moderation",
      "status": "error",
      "code": 438,
      "message": "There was an issue with the AI processing."
    }
  ]
}
```

**Ação:** verifique se a entrada de moderação é válida e usa um tipo de arquivo suportado, depois reenvie.

<Note>
  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.
</Note>

### Erros de análises do LinkedIn

**Código 475 — Revincule o perfil do LinkedIn para análises (HTTP 403)**

Retornado por [`POST /analytics/post`](/apis/analytics/post) e [`POST /analytics/social`](/apis/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.

```json theme={"system"}
{
  "action": "authorization",
  "status": "error",
  "code": 475,
  "message": "Your LinkedIn profile is missing the analytics permissions. Please re-link your LinkedIn profile to enable analytics.",
  "resolution": {
    "relink": true,
    "platform": "linkedin"
  }
}
```

**Ação:** peça ao proprietário da conta que revincule seu perfil do LinkedIn em [Social Accounts](https://app.ayrshare.com/social-accounts) para conceder os novos escopos de análises e, em seguida, tente a requisição de análises novamente. Após revincular, aguarde alguns minutos até o erro sumir: o Ayrshare armazena esse erro em cache brevemente e o LinkedIn também armazena em cache as permissões do token, então um perfil revinculado pode continuar retornando o código `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 o `id` 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](/apis/comments/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.

```json theme={"system"}
{
  "status": "error",
  "errors": [
    {
      "action": "get",
      "status": "error",
      "code": 288,
      "message": "TikTok video is still processing; the action is deferred until the post is live.",
      "platform": "tiktok"
    }
  ]
}
```

**Ação:** aguarde o TikTok concluir o processamento e tente novamente. Escute o [webhook Scheduled Action `tikTokPublished`](/apis/webhooks/actions#scheduled-action) ou consulte [/history](/apis/history/overview) até que o `id` da publicação seja o id numérico do vídeo resolvido. Um [first comment](/apis/post/overview#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](/multiple-users/manage-user-profiles#set-language-for-the-social-linking-page).

No header, inclua:

```json theme={"system"}
"Translate-Error-Message": "Language_Code"
```

Onde `Language_Code` é um dos [códigos de idioma](/iso-codes/language) disponíveis.

Por exemplo, o seguinte traduzirá o erro para francês.

```json theme={"system"}
"Translate-Error-Message": "fr" // Translate to French
```

Nosso sistema detectará automaticamente o idioma da mensagem de erro.