> ## 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 error de Ayrshare

> Códigos de error específicos devueltos por Ayrshare.

La API REST incluirá una respuesta con una lista de errores cuando corresponda.

<Info>
  Los errores devuelven un código de estado de 400, 401, 402, 403, 404, 429, 500, 502, 503 o 504. Un éxito devuelve un
  código de estado 200. Consulta [aquí](/errors/errors-http) para más detalles.
</Info>

Cada llamada a la API puede devolver diferentes errores según la solicitud específica y los problemas encontrados en la red social.
La respuesta de error contendrá detalles sobre lo que salió mal durante la llamada a la API.

Por ejemplo, una publicación considerada duplicada por Twitter y Facebook devolvería la siguiente respuesta.

```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"
}
```

Ten en cuenta:

<ul class="custom-bullets">
  <li>
    El campo `errors` contiene el arreglo de errores, uno por cada red social que tuvo un error.
  </li>

  <li>El `action` se refiere al tipo de error devuelto.</li>

  <li>
    El campo `status` de nivel superior será "error" si la llamada a la API falló. Por ejemplo, en una llamada a /post,
    si todas las publicaciones en las redes sociales tuvieron éxito, el campo `status` será "success"; de lo contrario,
    el campo status será "error".
  </li>

  <li>El campo `code` contiene el código de error de referencia de Ayrshare.</li>
  <li>El campo `message` incluye los detalles específicos del error.</li>
</ul>

### Manejo de errores

Debes gestionar cualquier respuesta de error y tomar la acción apropiada. Ocurrió un error si:

<ul class="custom-bullets">
  <li>El código de retorno de la respuesta no es `200`</li>
  <li>El status del JSON de respuesta es `error`</li>
</ul>

Por ejemplo, si el enlace de Facebook fue eliminado por tu usuario — cambió su contraseña o revocó el acceso de Ayrshare — se produciría la siguiente respuesta al publicar, con un código `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"
}
```

Una acción podría ser notificar a tu usuario mediante tu dashboard, SMS o correo electrónico.

Otro ejemplo es si la imagen publicada en Instagram tiene las dimensiones o la proporción incorrectas, con un código de respuesta `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?"
}
```

Una acción podría ser reenviar las imágenes con la proporción correcta.

### Códigos de error específicos de Instagram

Los siguientes códigos de error proporcionan detalles específicos sobre los fallos de publicación en Instagram, reemplazando al error genérico 138 cuando es posible.

**Código 435 — Rate limit de Instagram (HTTP 429)**

Las cuentas profesionales de Instagram (Business/Creator) están sujetas a un límite móvil de 50 publicaciones en 24 horas en la [Content Publishing API](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/content_publishing_limit/) de Meta (las cuentas personales no pueden publicar por la API en absoluto y, por lo tanto, nunca llegan a este límite). Cuando se supera el límite, Meta devuelve un error de rate limit. Ayrshare también expone `code: 435` cuando el endpoint de publicación de Meta devuelve HTTP 429 directamente o cuando el subcódigo de error subyacente (`1390008`) indica un throttle de publicación/comentario.

```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"
    }
  ]
}
```

**Acción:** espera a que se reinicie la ventana del rate limit antes de reintentar. Cuando Meta proporciona un header `Retry-After`, el valor (en segundos) se transmite en el campo `details`; espera al menos ese tiempo antes de reenviar.

**Código 436 — Timeout de procesamiento de medios de Instagram (HTTP 400)**

Instagram tardó demasiado en procesar el medio subido. Esto puede ocurrir con archivos de video grandes o durante períodos de alta carga en los servidores de 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"
    }
  ]
}
```

**Acción:** reintenta la publicación usando el endpoint [retry post](/apis/post/retry-post). Si el problema persiste, prueba a reducir el tamaño del archivo de medio.

**Código 447 — Trial Reels de Instagram: falta graduationStrategy (HTTP 400)**

Se devuelve cuando se proporciona `instagramOptions.trialParams` en una solicitud [`/post`](/apis/post/post) pero `graduationStrategy` falta, es `null` o es una cadena vacía. Los trial reels requieren una estrategia de graduación explícita — consulta [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"
    }
  ]
}
```

**Acción:** establece `instagramOptions.trialParams.graduationStrategy` como `"MANUAL"` o `"SS_PERFORMANCE"` y reintenta, o elimina `trialParams` si no querías publicar un trial reel.

**Código 448 — Trial Reels de Instagram: graduationStrategy inválido (HTTP 400)**

Se devuelve cuando `graduationStrategy` está presente pero no es exactamente `"MANUAL"` o `"SS_PERFORMANCE"`. La verificación distingue mayúsculas/minúsculas — valores como `"manual"` o `"ss_performance"` se rechazan. El campo `details` refleja el valor rechazado (truncado a 64 caracteres) para ayudar con la depuración.

```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"
    }
  ]
}
```

**Acción:** envía `graduationStrategy` como exactamente `"MANUAL"` o `"SS_PERFORMANCE"` (mayúsculas, tipo string).

**Código 449 — Trial Reels de Instagram: medio incompatible (HTTP 400)**

Se devuelve cuando el medio o la forma de la publicación no es elegible para un trial reel. Los trial reels deben ser un solo video `.mp4` o `.mov` — se rechazan los carruseles (más de una URL), las stories (`instagramOptions.stories: true`) y las extensiones que no sean de video. El campo `details` desambigua cuál sub-caso se activó.

```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"
    }
  ]
}
```

**Acción:** envía una única URL de video `.mp4` o `.mov` sin la flag `stories: true`. Elimina las entradas adicionales de `mediaUrls`, o elimina `trialParams` si querías publicar un carrusel/story normal.

**Código 258 — Error de estado de cuenta de Instagram (HTTP 400)**

Un fallo general de estado de cuenta de Instagram con el mensaje base "Error with Instagram." Aparece cuando Meta rechaza la solicitud debido al estado de la cuenta de Instagram conectada y no al contenido de la publicación.

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

Cuando el `error_subcode` subyacente de Meta es `2207085`, la respuesta también establece `relink: true` y `retryAvailable: true`, y el mensaje instruye al usuario a desvincular y volver a vincular la cuenta de Instagram, otorgando todos los permisos:

```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"
    }
  ]
}
```

**Acción:** para el sub-caso `2207085`, pide al usuario que desvincule y vuelva a vincular su cuenta de Instagram en [Social Accounts](https://app.ayrshare.com/social-accounts), otorgando todos los permisos solicitados, y luego reintente la publicación. Para otros errores de estado de cuenta, verifica que la cuenta de Instagram esté en buen estado en Meta y reintenta.

#### Retry disponible

A veces las redes sociales tienen un error irrecuperable, por ejemplo problemas de servidor, y la llamada termina fallando incluso después de numerosos reintentos.
En esos casos, nuestro sistema determinará si el error se puede reintentar y, si es así, el campo `retryAvailable` será `true`.

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

Luego puedes reintentar la llamada con el mismo payload.
Si es una publicación, puedes usar el endpoint [retry post](/apis/post/retry-post).

### Errores de BYO Key de X/Twitter

Los siguientes códigos de error son específicos de las operaciones de X/Twitter con BYO (Bring Your Own) keys:

**Código 272 - No se pudo verificar la identidad BYO de Twitter (HTTP 400)**

Ayrshare no pudo confirmar tu identidad de X/Twitter usando tus consumer keys BYO y los tokens OAuth almacenados en el momento de la vinculación. La forma de la respuesta varía según qué llamada la haya activado; ambas formas se corresponden con los tres sub-casos siguientes. Verifica cuál aplica iniciando sesión en [x.com](https://x.com) con la cuenta propietaria de la BYO Developer App.

La ruta de publicación emite una respuesta mínima:

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

La ruta de analíticas emite un mensaje más largo y autoexplicativo, y puede incluir un campo `details` con la cadena de error sin procesar de 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"
}
```

Cuando está presente, `details` refleja la pista del lado de X y es la señal única más fiable para determinar qué sub-caso aplica.

**Cuenta suspendida.** Al iniciar sesión en x.com aparece un aviso de suspensión. **Acción:** contacta con el soporte de X. Volver a vincular no restablecerá el acceso hasta que X reinstale la cuenta.

**Cuenta bloqueada.** Al iniciar sesión en x.com aparece un desafío de desbloqueo (CAPTCHA, verificación por teléfono, etc.). **Acción:** completa el desafío de desbloqueo en x.com y luego reintenta la solicitud. No es necesario volver a vincular.

**Discrepancia de identidad o key.** Tu cuenta de X está en buen estado en x.com, pero tus consumer keys BYO pertenecen a una X Developer App diferente que los tokens OAuth almacenados al vincular. **Acción:** vuelve a vincular X en Social Accounts y autoriza con la misma cuenta de X propietaria de la BYO Developer App.

**Código 416 — Créditos de X agotados (HTTP 402)**

Tu cuenta de X Developer no tiene créditos de API cargados. Todas las llamadas a la API de X requieren 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"
}
```

**Acción:** ve a [console.x.com](https://console.x.com) → Billing → Credits y compra créditos. Incluso \$5 son suficientes para cientos de llamadas a la API.

**Código 417 — Permisos de app de OAuth 1.0a (HTTP 403)**

Tu Access Token de X no tiene los permisos correctos para la operación 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"
}
```

También puedes ver el header de respuesta `x-access-level: read`, que confirma que tu Access Token se generó con permisos de solo lectura.

**Acción:** en la X Developer Console, actualiza los permisos de tu app a **Read and write and Direct message** y luego regenera tu Access Token en Keys and tokens. El nuevo token heredará los permisos actualizados. Consulta la [Guía de configuración de X BYO Key](/dashboard/connect-social-accounts/x-twitter-byo-keys#troubleshooting) para más detalles.

**Código 419 - Faltan credenciales BYO (HTTP 400)**

Las operaciones de X/Twitter requieren credenciales de API BYO en los headers de la solicitud. Ayrshare devuelve el código 419 cuando faltan ambos headers, y también cuando solo hay uno del par. La cadena `message` varía dependiendo de qué header(s) falten.

Cuando faltan tanto `X-Twitter-OAuth1-Api-Key` como `X-Twitter-OAuth1-Api-Secret`:

```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"
}
```

Cuando solo está presente uno del par (por ejemplo, la key sin el 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"
}
```

**Acción:** envía `X-Twitter-OAuth1-Api-Key` y `X-Twitter-OAuth1-Api-Secret` en cada solicitud dirigida a X. Si proporcionas uno sin el otro, la solicitud se rechaza con el mismo código. Consulta la [Referencia de headers de X BYO Keys](/dashboard/connect-social-accounts/x-twitter-byo-keys#header-reference) para ver la lista completa de headers.

**Código 423 — OAuth heredado de X/Twitter ya no soportado (HTTP 403)**

Se devuelve cuando una solicitud a X/Twitter depende del path OAuth heredado (no BYO), que ya no está soportado. El acceso a la API de X ahora requiere tus propias credenciales de X Developer App proporcionadas mediante headers de solicitud.

```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"
}
```

**Acción:** configura una X Developer App y envía los headers `X-Twitter-OAuth1-Api-Key` y `X-Twitter-OAuth1-Api-Secret` en cada solicitud dirigida a X. Consulta la [Guía de configuración de X BYO Key](/dashboard/connect-social-accounts/x-twitter-byo-keys) para ver todos los pasos de configuración.

### Errores de mejora de captions

**Código 441 — Falló la mejora de caption (HTTP 502)**

Se devuelve cuando una mejora de caption (por ejemplo [`shortenLinks`](/apis/post/post)) falla en una o más plataformas al preparar una publicación. Cada plataforma afectada aparece en el arreglo `errors` con `source: "handlePostAdditions"` y `code: 441`.

Cuando solo fallan algunas plataformas, las demás plataformas siguen publicando con éxito y sus resultados aparecen en `postIds`. En ese caso, el `status` de nivel superior es `"error"` pero `postIds` no está vacío — los clientes deben tratar `status` y `errors[]` como complementarios y no mutuamente excluyentes.

```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": "..."
}
```

Si **todas** las plataformas fallan en la mejora, la respuesta es un `code: 441` de nivel superior con HTTP `502` y no se crea ninguna publicación:

```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>"
    }
  ]
}
```

**Acción:** los fallos de mejora de caption suelen ser transitorios (el servicio de acortador o mejora subyacente devolvió un error).

* **Si `postIds` no está vacío** (algunas plataformas publicaron con éxito), **no** vuelvas a enviar todo el conjunto de plataformas — eso duplicaría la publicación en las plataformas exitosas. En su lugar, inspecciona `errors[]` para identificar las plataformas que fallaron y reintenta la solicitud solo con esas plataformas, o confía en tu propio flujo de reintento idempotente.
* **Si `postIds` está vacío o falta** (fallo total al programar/publicar), puedes reintentar la solicitud completa de forma segura.
* Si el fallo persiste, envía la publicación sin la flag de mejora (por ejemplo, elimina `shortenLinks`) o contacta con soporte.

### Errores de acceso del crawler / obtención de medios

**Código 440 — La red social no pudo descargar el medio (HTTP 400)**

Se devuelve cuando el crawler de publicación de la plataforma no puede descargar el `mediaUrl` que proporcionaste — normalmente porque `robots.txt` o una regla de WAF/bot-fight está bloqueando al crawler (por ejemplo, el `facebookexternalhit` de Meta). La cadena `details` proviene de la plataforma upstream y suele ser el texto del error 2207052 de 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 — Obtención de medio de Instagram bloqueada (HTTP 400)**

Código de reserva para fallos de obtención de medios de Instagram cuando la respuesta upstream es menos específica que la que activa el código 440. La cadena `details` suele contener `"Restricted by robots.txt"` o `"HTTP error code 403"`. El código 138 también se usa para problemas de relación de aspecto/formato y otros errores genéricos de Instagram, por lo que la variante de obtención de medios es identificable por la cadena `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 — Error al publicar en Threads**

Se devuelve cuando falla la publicación en Threads. Lo más común es que sea causado por el mismo problema de obtención de medios que los códigos 440/138 al publicar en ambas plataformas con el mismo `mediaUrl`. La API de Threads no devuelve cadenas de detalle, por lo que el diagnóstico normalmente requiere buscar un 440 o 138 de Instagram coocurrente en la misma publicación.

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

**Acción:** consulta [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) para una solución de problemas completa, incluyendo fragmentos de `robots.txt` y un comando de verificación.

### Rate limit de analíticas de Facebook

**Código 444 — Rate limit de analíticas de una Página de Facebook (HTTP 429)**

Se devuelve cuando una Página de Facebook ha excedido el rate limit por Página de Meta en el endpoint de analíticas. El error subyacente de Meta es `80001` ("There have been too many calls to this Page account."). La Página sigue vinculada y la publicación sigue funcionando — solo se limita el fan-out de analíticas para esa Página.

Cuando se detecta el throttle para una única publicación en una respuesta de [`/history/facebook`](/apis/history/history-platform) o [analytics](/apis/analytics/social), cada publicación afectada lleva `code: 444` en `facebook.code` con `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": "..."
}
```

**Acción:** espera unos minutos y reintenta. La ventana de rate limit por Página de Meta suele resolverse en menos de una hora sin necesidad de acción sobre la Página. **No** pidas al usuario que vuelva a vincular la cuenta — se trata de un throttle transitorio del lado de Meta, no de un fallo de autorización.

<Warning>
  Si antes manejabas esta condición como `code: 161` ("Facebook authorization error … unlink and re-link"), actualiza tu integración para reconocer `code: 444` y reintentar con backoff en lugar de iniciar un flujo de relink. La clasificación `161` se corrigió en abril de 2026.
</Warning>

### Verificación de identidad de Meta

**Código 326 — Se requiere verificación de identidad de Meta (HTTP 403)**

Se devuelve cuando Meta requiere una verificación de identidad adicional para la cuenta conectada antes de aceptar la solicitud. Esto aplica en todas las plataformas de Meta — Facebook, Instagram, Grupos de Facebook, Threads y Messenger. Volver a conectar la cuenta **no** resuelve esto; la verificación debe completarse en el lado de 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"
    }
  ]
}
```

**Acción:** haz que el propietario de la cuenta complete la verificación de identidad de Meta en [Meta Business Support](https://www.facebook.com/business-support-home) y luego reintenta la solicitud. **No** pidas al usuario que vuelva a vincular la cuenta — volver a vincular no resolverá este requisito.

### Restricción de cuenta de Facebook

**Código 476 — Restricción de cuenta de Facebook (HTTP 400)**

Se devuelve cuando una publicación en Facebook falla porque Meta ha colocado una restricción en la cuenta (subcódigos de error de Meta `2424009` y `1404078`, o la redacción de restricción de Meta cuando el error no lleva subcódigo). Se trata de una restricción a nivel de cuenta, no un fallo transitorio de publicación — es **no reintentable** y **no** lleva la flag `retryAvailable`. Reenviar la misma publicación no tendrá éxito hasta que la restricción se resuelva con Meta. La cuenta sigue vinculada a Ayrshare; no se requiere volver a vincular.

Meta no devuelve el motivo específico de la restricción a través de la API, por lo que el cliente debe consultar directamente la página Account Status de Meta para ver el motivo y apelar. Cuando Meta suministra su propio texto verbatim, Ayrshare lo expone en el campo `details`. Ayrshare también envía al propietario de la cuenta un correo electrónico de notificación cuando se detecta la restricción.

```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"
    }
  ]
}
```

**Acción:** inicia sesión en Facebook, haz clic en tu foto de perfil (arriba a la derecha), abre la sección Help y selecciona **Account Status**. El asistente de soporte de Meta allí muestra el motivo específico de la restricción y te permite apelar. Como la restricción la aplica Meta a nivel de cuenta, este código es no reintentable — no crees lógica de reintento automático a su alrededor; resuelve primero la restricción con Meta.

### Errores de conversión de formato de imagen

Ayrshare convierte automáticamente imágenes WebP, HEIC y AVIF a JPEG antes de publicarlas en plataformas que no las aceptan (Instagram, LinkedIn, TikTok, Google My Business, Threads y Snapchat para WebP; todas las plataformas para HEIC y AVIF). La conversión se ejecuta de forma transparente en el momento del envío. Los tres errores siguientes se activan solo cuando la propia pipeline de conversión no puede completarse; si la imagen de origen ya está en un formato compatible, no se intenta ninguna conversión y estos códigos no aparecerán.

**Código 450 — Falló la conversión de formato de imagen (HTTP 400)**

La imagen se descargó pero no pudo reencodificarse como JPEG. Las causas más comunes son un archivo de origen corrupto, un formato interno inesperado dentro del contenedor o una imagen que excede el límite de tamaño de conversión.

```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"
    }
  ]
}
```

**Acción:** abre el `mediaUrl` de origen directamente en un navegador para confirmar que se renderiza. Si lo hace, vuelve a exportar la imagen a un JPEG o PNG limpio y reintenta la publicación.

**Código 451 — Falló la descarga de imagen para conversión (HTTP 400)**

La pipeline de conversión no pudo obtener la imagen de origen. Las causas típicas incluyen una respuesta 4xx/5xx del origen, un timeout de red, una cadena de redirecciones que excede el límite de saltos, o una URL que resuelve a una dirección no pública (bloqueada por la protección SSRF). El campo `details`, cuando está presente, contiene la cadena de causa subyacente.

```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"
    }
  ]
}
```

**Acción:** confirma que el `mediaUrl` es accesible públicamente (sin autenticación, sin bloqueos por `robots.txt`, resuelto por HTTPS). Si la URL redirige, asegúrate de que el destino final también sea público y no esté en una red privada.

**Código 452 — Falló la subida de la imagen convertida (HTTP 500)**

La conversión tuvo éxito pero Ayrshare no pudo colocar el JPEG convertido en su bucket de almacenamiento temporal. Este es un fallo interno del lado de Ayrshare y se puede reintentar.

```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"
    }
  ]
}
```

**Acción:** reintenta la publicación. Si el error persiste tras varios reintentos, contacta con soporte con el `mediaUrl` y una marca de tiempo aproximada.

### Errores transitorios de subida a YouTube

Los siguientes códigos de error proporcionan señales específicas para fallos de subida a YouTube que suelen ser transitorios y seguros de reintentar. Ambas respuestas incluyen `retryAvailable: true`, por lo que las integraciones pueden tomar decisiones en función de ese booleano en lugar del código de estado HTTP.

La mayoría de las respuestas previas `code: 176` para subidas a YouTube ahora se enrutan a **453** (timeout transitorio) o **454** (servicio transitoriamente no disponible), ambas con `retryAvailable: true`. Si tu integración filtra por HTTP 500 para reintentar subidas a YouTube, cambia a filtrar por el campo `retryAvailable` en el body de la respuesta.

**Código 453 — Timeout en la subida a YouTube (HTTP 504)**

Se devuelve cuando la pipeline de ingesta de YouTube de Google agotó el tiempo de espera al aceptar la subida. Suele ser transitorio y se resuelve solo en uno o dos 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"
    }
  ]
}
```

**Acción:** reintenta la publicación después de 1-2 minutos con backoff exponencial. Toma decisiones en función del campo `retryAvailable` en el body de la respuesta y no del status HTTP para detectar fallos reintentables. Puedes usar el endpoint [retry post](/apis/post/retry-post) para reenviar el mismo payload.

**Código 454 — Servicio de subida a YouTube temporalmente no disponible (HTTP 503)**

Se devuelve cuando el endpoint de subida de YouTube devuelve un status 5xx, o cuando la conexión a YouTube se reinició o agotó el tiempo de espera a nivel de socket (`ECONNRESET`, `ETIMEDOUT`, `ESOCKETTIMEDOUT`). Estas condiciones son transitorias.

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

**Acción:** reintenta la publicación con backoff exponencial. Toma decisiones en función del campo `retryAvailable` en el body de la respuesta y no del status HTTP para detectar fallos reintentables. Puedes usar el endpoint [retry post](/apis/post/retry-post) para reenviar el mismo payload.

### Errores de miniatura de YouTube Código 307

El código `307` se devuelve cuando no se puede aplicar un `thumbNail` personalizado de YouTube. Cuando el propio video se publica con éxito, esto **no** hace que la publicación falle — el resultado de YouTube mantiene `status: "success"` y expone el fallo de forma aditiva en un arreglo `warnings` (`feature: "thumbnail"`, `code: 307`). El sub-objeto heredado `thumbnail` se conserva por compatibilidad hacia atrás.

La causa más común es un **canal de YouTube no verificado**. Cuando un canal no ha completado la verificación por teléfono, YouTube devuelve un `403` upstream con el mensaje genérico `"The authenticated user doesn't have permissions to upload and set custom video thumbnails"`. Esa redacción suena a un problema de OAuth, pero en la práctica casi siempre es un problema de verificación, así que verifica primero el canal. Volver a vincular la cuenta de YouTube es una causa secundaria.

```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>"
    }
  ]
}
```

Ayrshare también valida la miniatura antes de publicar cuando es posible: el archivo debe ser **PNG o JPG/JPEG**, **de 2 MB o menos** y servido desde una **URL alcanzable**.

Un problema de miniatura **nunca hace fallar la publicación** — el video siempre se publica y el fallo siempre se expone como una entrada no fatal en `warnings` (el `status` de nivel superior sigue siendo `"success"`). Esto se cumple independientemente de cuándo se detecte el problema:

* **Detectado antes de la subida.** Cuando la validación previa a la publicación puede determinar definitivamente que la miniatura es inválida (tipo de archivo incorrecto, más de 2 MB confirmado, o URL inalcanzable), Ayrshare omite la miniatura, publica el video de todos modos e informa el motivo preciso en `warnings` — así evitas un intento de subida condenado y obtienes un mensaje más claro del que devolvería el proveedor.
* **Detectado después de la subida.** Cuando el fallo solo es detectable una vez que YouTube procesa la solicitud (por ejemplo, el `403` de canal no verificado o un `413` por una imagen demasiado grande), el video ya está publicado y el fallo se expone en el mismo arreglo `warnings`.

En cualquier caso, la respuesta se ve como el ejemplo `status: "success"` + `warnings` mostrado antes en esta sección.

**Acción:** verifica tu canal de YouTube en [https://www.youtube.com/verify](https://www.youtube.com/verify) (verificación por teléfono). Si tu canal ya está verificado y las miniaturas siguen fallando, desvincula y vuelve a vincular tu cuenta de YouTube en [Social Accounts](https://app.ayrshare.com/social-accounts) y otorga todos los permisos. Consulta [Miniatura de YouTube no aplicada (canal no verificado)](/help-center/technical-support/youtube_thumbnail_unverified_channel) para la guía completa de solución de problemas.

### Errores de publicación en Reddit

**Código 442 — Baneado de un subreddit de Reddit (HTTP 400)**

Se devuelve cuando la cuenta ha sido baneada de publicar en el subreddit de destino. Esto **no** se puede reintentar — la publicación no tendrá éxito si se reenvía tal cual. El mensaje incluye el nombre del subreddit afectado (por ejemplo, `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"
    }
  ]
}
```

**Acción:** elimina el subreddit baneado de tus subreddits objetivo. Reintentar la publicación sin cambios no tendrá éxito.

**Código 443 — Palabra no permitida en el título de Reddit (HTTP 400)**

Se devuelve cuando un subreddit rechaza la publicación porque su título contiene una palabra no permitida. Edita el título antes de reintentar — reenviar tal cual no tendrá éxito. El mensaje incluye el nombre del subreddit afectado (por ejemplo, `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"
    }
  ]
}
```

**Acción:** edita el título de la publicación para eliminar la palabra no permitida y luego reintenta.

### Errores de moderación

**Código 438 — Entrada de moderación rechazada (HTTP 400)**

Devuelto por [`POST /validate/moderation`](/apis/post/post) cuando el proveedor de IA rechaza la entrada proporcionada — por ejemplo, un tipo de archivo no soportado. Este es un problema de entrada en la solicitud, no un fallo transitorio de procesamiento.

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

**Acción:** verifica que la entrada de moderación sea válida y use un tipo de archivo soportado, luego reenvíala.

<Note>
  Contrasta el código 438 con el **código 331**. El código 331 cubre el mismo escenario de moderación pero representa un fallo genuino de procesamiento del lado del proveedor (HTTP 500, mensaje "There was an issue with the AI processing. Please try again."). El código 331 es un fallo transitorio del lado del servidor que puedes reintentar, mientras que el código 438 indica que la propia entrada fue rechazada y debe corregirse antes de reintentar.
</Note>

### Errores de analíticas de LinkedIn

**Código 475 — Volver a vincular el perfil de LinkedIn para analíticas (HTTP 403)**

Devuelto por [`POST /analytics/post`](/apis/analytics/post) y [`POST /analytics/social`](/apis/analytics/social) para un perfil personal (member) de LinkedIn que se vinculó antes de que se lanzaran las analíticas de miembros. A estos perfiles les faltan los scopes de analíticas de miembros de LinkedIn (`r_member_postAnalytics`, `r_member_profileAnalytics`), por lo que LinkedIn rechaza la solicitud de analíticas. La publicación no se ve afectada.

```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"
  }
}
```

**Acción:** haz que el propietario de la cuenta vuelva a vincular su perfil de LinkedIn en [Social Accounts](https://app.ayrshare.com/social-accounts) para otorgar los nuevos scopes de analíticas, y luego reintente la solicitud de analíticas. Después de volver a vincular, deja pasar unos minutos antes de que el error se aclare: Ayrshare cachea este error brevemente y LinkedIn también cachea los permisos del token, por lo que un perfil re-vinculado puede seguir devolviendo el código `475` durante unos 5-10 minutos antes de que las analíticas funcionen.

### Errores de comentarios de TikTok

**Código 288 — Comentario de TikTok diferido / la publicación aún se está procesando (HTTP 400)**

TikTok procesa videos de forma asíncrona, por lo que el `id` de una publicación recién publicada es `"pending"` hasta que el webhook `post.publish.publicly_available` de TikTok resuelve el id real del video. Una solicitud de [get-comments](/apis/comments/get-comments), comment o reply contra una publicación que aún se está procesando (o cuya `id` es `"failed"`) se rechaza antes de cualquier llamada a TikTok y devuelve el código 288 en lugar de un fallo genérico.

```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"
    }
  ]
}
```

**Acción:** espera a que TikTok termine de procesar y luego reintenta. Escucha el [webhook `tikTokPublished` Scheduled Action](/apis/webhooks/actions#scheduled-action) o consulta periódicamente [/history](/apis/history/overview) hasta que el `id` de la publicación sea el id numérico del video resuelto. Un [primer comentario](/apis/post/overview#first-comment) se publica automáticamente una vez que la publicación se resuelve, por lo que no necesita ser reintentado. Para una publicación `"failed"`, el mensaje indica en su lugar que el video no se publicó y la acción no se ejecutará.

### Traducción del mensaje de error

El mensaje de error de respuesta de la API se puede traducir automáticamente al idioma que elijas.
Esto es útil si quieres mostrar el error directamente a tu usuario en su idioma preferido.

Consulta aquí si quieres [elegir el idioma de la página de vinculación social](/multiple-users/manage-user-profiles#set-language-for-the-social-linking-page).

En el header incluye:

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

Donde el `Language_Code` es uno de los [códigos de idioma](/iso-codes/language) disponibles.

Por ejemplo, lo siguiente traducirá el error al francés.

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

Nuestro sistema detectará automáticamente el idioma del mensaje de error.