Codes d'erreur Ayrshare - Ayrshare API Documentation

L’API REST inclut, le cas échéant, une réponse contenant une liste d’erreurs.

Les erreurs renvoient un code de statut 400, 401, 402, 403, 404, 429, 500, 502, 503 ou 504. Un succès renvoie un code de statut 200. Voir ici pour plus de détails.

Chaque appel API peut renvoyer différentes erreurs en fonction de la requête spécifique et de tout problème rencontré côté réseau social. La réponse d’erreur contiendra des détails sur ce qui s’est mal passé pendant l’appel API. Par exemple, une publication considérée comme un doublon par Twitter et Facebook renverrait la réponse suivante.

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

Veuillez noter :

Le champ errors contient le tableau des erreurs, une par réseau social ayant rencontré une erreur.
L’action fait référence au type d’erreur renvoyé.
Le champ status de niveau supérieur vaut « error » si l’appel API a échoué. Par exemple, pour un appel /post, si toutes les publications sur les réseaux sociaux ont réussi, le champ status vaudra « success », sinon il vaudra « error ».
Le champ code contient le code d’erreur de référence Ayrshare.
Le champ message contient les détails spécifiques de l’erreur.

Gestion des erreurs

Vous devez gérer toute réponse d’erreur et prendre l’action appropriée. Une erreur s’est produite si :

Le code de retour de la réponse n’est pas 200
Le statut de la réponse JSON est error

Par exemple, si la connexion Facebook a été supprimée par votre utilisateur — il a changé son mot de passe ou a supprimé l’accès d’Ayrshare — la réponse suivante se produirait lors d’une publication, avec un code de réponse 400 Bad Request.

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

Une action possible serait d’avertir votre utilisateur via votre tableau de bord, par SMS ou par e-mail. Un autre exemple concerne une image Instagram publiée avec de mauvaises dimensions ou un mauvais ratio, avec un code de réponse 400 Bad Request :

{
  "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?"
}

Une action possible serait de renvoyer les images avec le ratio correct.

Codes d’erreur spécifiques à Instagram

Les codes d’erreur suivants fournissent des détails spécifiques sur les échecs de publication Instagram, en remplaçant, lorsque cela est possible, l’erreur générique 138. Code 435 — Instagram Rate Limit (HTTP 429) Les comptes Instagram professionnels (Business / Creator) sont soumis à une limite glissante de 50 publications sur 24 heures via la Content Publishing API de Meta (les comptes personnels ne peuvent pas publier via l’API, ils n’atteignent donc jamais cette limite). Lorsque le plafond est dépassé, Meta renvoie une erreur de limite de débit. Ayrshare renvoie également code: 435 lorsque l’endpoint de publication de Meta renvoie directement un HTTP 429 ou lorsque le sous-code d’erreur sous-jacent (1390008) indique un throttle de publication / commentaire.

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

Action : attendez que la fenêtre de limite de débit se réinitialise avant de réessayer. Lorsque Meta fournit un en-tête Retry-After, la valeur (en secondes) est transmise dans le champ details — attendez au moins ce délai avant de resoumettre. Code 436 — Instagram Media Processing Timeout (HTTP 400) Instagram a mis trop de temps à traiter le média téléversé. Cela peut se produire avec des fichiers vidéo volumineux ou pendant les périodes de forte charge sur les serveurs de Meta.

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

Action : réessayez la publication en utilisant l’endpoint retry post. Si le problème persiste, essayez de réduire la taille du fichier média. Code 447 — Instagram Trial Reels : graduationStrategy manquant (HTTP 400) Renvoyé lorsque instagramOptions.trialParams est fourni sur une requête /post mais que graduationStrategy est manquant, null ou une chaîne vide. Les trial reels nécessitent une stratégie de graduation explicite — voir Trial Reels.

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

Action : définissez instagramOptions.trialParams.graduationStrategy sur "MANUAL" ou "SS_PERFORMANCE" et réessayez, ou supprimez trialParams si vous n’aviez pas l’intention de publier un trial reel. Code 448 — Instagram Trial Reels : graduationStrategy invalide (HTTP 400) Renvoyé lorsque graduationStrategy est présent mais n’est pas exactement "MANUAL" ou "SS_PERFORMANCE". La vérification est sensible à la casse — des valeurs comme "manual" ou "ss_performance" sont rejetées. Le champ details reprend la valeur rejetée (tronquée à 64 caractères) pour faciliter le débogage.

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

Action : envoyez graduationStrategy exactement sous la forme "MANUAL" ou "SS_PERFORMANCE" (en majuscules, de type string). Code 449 — Instagram Trial Reels : média incompatible (HTTP 400) Renvoyé lorsque le média ou la forme de la publication n’est pas éligible à un trial reel. Les trial reels doivent être une seule vidéo .mp4 ou .mov — les carrousels (plusieurs URL), les stories (instagramOptions.stories: true) et les extensions non vidéo sont tous rejetés. Le champ details précise quel sous-cas a été déclenché.

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

Action : soumettez une seule URL vidéo .mp4 ou .mov sans le drapeau stories: true. Supprimez les entrées mediaUrls supplémentaires, ou supprimez trialParams si vous prévoyiez une publication carrousel/story classique. Code 258 — Erreur d’état de compte Instagram (HTTP 400) Un échec général lié à l’état du compte Instagram, avec le message de base « Error with Instagram. » Cela apparaît lorsque Meta rejette la requête en raison de l’état du compte Instagram connecté, et non du contenu de la publication.

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

Lorsque le sous-code Meta sous-jacent error_subcode est 2207085, la réponse ajoute relink: true et retryAvailable: true, et le message indique à l’utilisateur de déconnecter et reconnecter le compte Instagram en accordant toutes les autorisations :

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

Action : pour le sous-cas 2207085, invitez l’utilisateur à déconnecter et reconnecter son compte Instagram dans Social Accounts en accordant toutes les autorisations demandées, puis réessayez la publication. Pour les autres erreurs d’état de compte, vérifiez que le compte Instagram est en règle chez Meta et réessayez.

Retry Available

Parfois, les réseaux sociaux rencontrent une erreur irrécupérable, par exemple des problèmes serveur, et l’appel finit par échouer même après de nombreuses tentatives. Dans ces cas, notre système détermine si l’erreur est réessayable et, si oui, le champ retryAvailable sera true.

{
  "retryAvailable": true
}

Vous pouvez alors réessayer l’appel avec la même charge utile. S’il s’agit d’une publication, vous pouvez utiliser l’endpoint retry post.

Erreurs BYO Key X/Twitter

Les codes d’erreur suivants sont spécifiques aux opérations BYO (Bring Your Own) key pour X/Twitter : Code 272 - Failed to Verify BYO Twitter Identity (HTTP 400) Ayrshare n’a pas pu confirmer votre identité X/Twitter à l’aide de vos consumer keys BYO et des tokens OAuth stockés au moment de la connexion. La forme de la réponse varie selon l’appel qui l’a déclenchée ; les deux formes correspondent aux mêmes trois sous-cas ci-dessous. Vérifiez lequel s’applique en vous connectant à x.com avec le compte propriétaire de la BYO Developer App. Le chemin de publication émet une réponse minimale :

{
  "status": "error",
  "code": 272,
  "message": "Failed to verify BYO Twitter identity",
  "platform": "twitter"
}

Le chemin de statistiques émet un message plus long et auto-documenté et peut inclure un champ details portant la chaîne d’erreur brute de X :

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

Lorsqu’il est présent, details reflète l’indication côté X et constitue le signal unique le plus fiable pour déterminer lequel des sous-cas ci-dessous s’applique. Compte suspendu. Vous connecter à x.com affiche un avis de suspension. Action : contactez le support X. La reconnexion ne restaurera pas l’accès tant que X n’aura pas réintégré le compte. Compte verrouillé. Vous connecter à x.com déclenche un défi de déverrouillage (CAPTCHA, vérification par téléphone, etc.). Action : effectuez le défi de déverrouillage sur x.com, puis réessayez la requête. Aucune reconnexion n’est requise. Discordance d’identité ou de clés. Votre compte X est en règle sur x.com, mais vos consumer keys BYO appartiennent à une X Developer App différente de celle des tokens OAuth stockés au moment de la connexion. Action : reconnectez X dans Social Accounts et autorisez avec le même compte X que celui qui possède la BYO Developer App. Code 416 — X Credits Depleted (HTTP 402) Votre compte X Developer n’a plus de crédits d’API chargés. Tous les appels à l’API X nécessitent des crédits.

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

Action : allez sur console.x.com → Billing → Credits et achetez des crédits. Même $5 suffisent pour des centaines d’appels API. Code 417 — OAuth 1.0a App Permissions (HTTP 403) Votre X Access Token n’a pas les autorisations correctes pour l’opération demandée.

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

Vous pouvez également voir l’en-tête de réponse x-access-level: read, qui confirme que votre Access Token a été généré avec des autorisations en lecture seule. Action : dans la X Developer Console, mettez à jour les autorisations de votre application sur Read and write and Direct message, puis régénérez votre Access Token dans Keys and tokens. Le nouveau token héritera des autorisations mises à jour. Voir le Guide de configuration BYO Key pour X pour plus de détails. Code 419 - Missing BYO Credentials (HTTP 400) Les opérations X/Twitter nécessitent des identifiants d’API BYO dans les en-têtes de la requête. Ayrshare renvoie le code 419 lorsque les deux en-têtes sont manquants, et également lorsqu’un seul des deux est présent. La chaîne message varie selon le ou les en-têtes manquants. Lorsque X-Twitter-OAuth1-Api-Key et X-Twitter-OAuth1-Api-Secret sont tous les deux manquants :

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

Lorsqu’un seul des deux est présent (par exemple, la clé sans le secret) :

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

Action : envoyez X-Twitter-OAuth1-Api-Key et X-Twitter-OAuth1-Api-Secret sur chaque requête ciblant X. Si vous en fournissez un sans l’autre, la requête est rejetée avec le même code. Voir la référence des en-têtes X BYO Keys pour la liste complète des en-têtes. Code 423 — Legacy X/Twitter OAuth No Longer Supported (HTTP 403) Renvoyé lorsqu’une requête X/Twitter s’appuie sur l’ancien chemin OAuth (non-BYO), qui n’est plus pris en charge. L’accès à l’API X nécessite désormais vos propres identifiants X Developer App fournis via les en-têtes de la requête.

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

Action : configurez une X Developer App et envoyez les en-têtes X-Twitter-OAuth1-Api-Key et X-Twitter-OAuth1-Api-Secret sur chaque requête ciblant X. Voir le Guide de configuration BYO Key pour X pour toutes les étapes de configuration.

Erreurs d’amélioration de légende

Code 441 — Caption Enhancement Failed (HTTP 502) Renvoyé lorsqu’une amélioration de légende (par exemple shortenLinks) échoue pour une ou plusieurs plateformes lors de la préparation d’une publication. Chaque plateforme affectée apparaît dans le tableau errors avec source: "handlePostAdditions" et code: 441. Lorsque seules certaines plateformes échouent, les autres publient tout de même avec succès et leurs résultats apparaissent dans postIds. Dans ce cas, le status de niveau supérieur est "error" mais postIds n’est pas vide — les clients doivent traiter status et errors[] comme complémentaires plutôt que mutuellement exclusifs.

{
  "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 toutes les plateformes échouent à l’amélioration, la réponse est un code: 441 de niveau supérieur avec un HTTP 502 et aucune publication n’est créée :

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

Action : les échecs d’amélioration de légende sont généralement transitoires (le service sous-jacent de raccourcissement ou d’amélioration a renvoyé une erreur).

Si postIds n’est pas vide (certaines plateformes ont publié avec succès), ne resoumettez pas l’ensemble complet des plateformes — cela dupliquerait la publication sur les plateformes réussies. Inspectez plutôt errors[] pour identifier les plateformes en échec et relancez la requête avec uniquement ces plateformes, ou appuyez-vous sur votre propre flux de retry idempotent.
Si postIds est vide ou absent (échec total au moment de la planification/publication), vous pouvez relancer la requête complète en toute sécurité.
Si l’échec persiste, soumettez la publication sans le drapeau d’amélioration (par exemple, supprimez shortenLinks) ou contactez le support.

Erreurs de récupération de média / d’accès du crawler

Code 440 — Social Network Could Not Download Media (HTTP 400) Renvoyé lorsque le crawler de publication de la plateforme ne peut pas télécharger le mediaUrl que vous avez fourni — le plus souvent parce que robots.txt ou une règle WAF / bot-fight bloque le crawler (par exemple facebookexternalhit de Meta). La chaîne details provient de la plateforme en amont et correspond souvent au texte d’erreur Meta/Instagram 2207052.

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

Code 138 — Instagram Media Fetch Blocked (HTTP 400) Code de repli pour les échecs de récupération de média Instagram lorsque la réponse en amont est moins précise que celle qui déclenche le code 440. La chaîne details contient généralement "Restricted by robots.txt" ou "HTTP error code 403". Le code 138 est également utilisé pour des problèmes de ratio / format et d’autres erreurs Instagram génériques, de sorte que la variante « échec de récupération de média » est identifiable par la chaîne details.

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

Code 379 — Threads Posting Error Renvoyé lorsque la publication sur Threads échoue. Le plus souvent causé par le même problème de récupération de média que les codes 440 / 138 lors d’une publication sur les deux plateformes avec le même mediaUrl. L’API Threads ne renvoie pas de chaînes de détails, donc le diagnostic nécessite généralement de vérifier la présence d’une erreur Instagram 440 ou 138 concomitante lors de la même publication.

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

Action : consultez Meta Media Crawler Blocked pour un dépannage complet, incluant des extraits de robots.txt et une commande de vérification.

Limite de débit des statistiques Facebook

Code 444 — Facebook Page Analytics Rate Limit (HTTP 429) Renvoyé lorsqu’une Page Facebook a dépassé la limite de débit par Page de Meta sur l’endpoint de statistiques. L’erreur Meta sous-jacente est 80001 (« There have been too many calls to this Page account. »). La Page reste connectée et la publication continue de fonctionner — seule la diffusion des statistiques pour cette Page est limitée. Lorsque le throttle est détecté pour une seule publication dans une réponse /history/facebook ou analytics, chaque publication affectée porte code: 444 sous facebook.code avec errCode: 80001 :

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

Action : attendez quelques minutes et réessayez. La fenêtre de limite de débit par Page de Meta se résout généralement dans l’heure sans aucune action sur la Page. Ne demandez pas à l’utilisateur de reconnecter le compte — il s’agit d’un throttle transitoire côté Meta, et non d’un échec d’autorisation.

Si vous traitiez auparavant cette condition comme code: 161 (« Facebook authorization error … unlink and re-link »), mettez à jour votre intégration pour reconnaître code: 444 et réessayer avec un backoff au lieu d’initier un flux de reconnexion. La classification 161 a été corrigée en avril 2026.

Vérification d’identité Meta

Code 326 — Meta Identity Verification Required (HTTP 403) Renvoyé lorsque Meta exige une vérification d’identité supplémentaire pour le compte connecté avant d’accepter la requête. Cela s’applique à toutes les plateformes Meta — Facebook, Instagram, Facebook Groups, Threads et Messenger. Reconnecter le compte ne résout pas ce problème ; la vérification doit être effectuée côté Meta.

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

Action : demandez au propriétaire du compte d’effectuer la vérification d’identité de Meta sur Meta Business Support, puis réessayez la requête. Ne demandez pas à l’utilisateur de reconnecter le compte — la reconnexion ne lèvera pas cette exigence.

Restriction de compte Facebook

Code 476 — Facebook Account Restriction (HTTP 400) Renvoyé lorsqu’une publication sur Facebook échoue parce que Meta a imposé une restriction sur le compte (sous-codes d’erreur Meta 2424009 et 1404078, ou formulation de restriction de Meta lorsque l’erreur ne porte pas de sous-code). Il s’agit d’une restriction au niveau du compte, et non d’un simple problème transitoire de publication — elle est non réessayable et ne porte pas de drapeau retryAvailable. Resoumettre la même publication n’aboutira pas tant que la restriction n’est pas résolue avec Meta. Le compte reste connecté à Ayrshare ; aucune reconnexion n’est nécessaire. Meta ne renvoie pas la raison spécifique de la restriction via l’API, donc le client doit vérifier directement la page Account Status de Meta pour voir la raison et faire appel. Lorsque Meta fournit son propre texte verbatim, Ayrshare l’affiche dans le champ details. Ayrshare envoie également un e-mail de notification au propriétaire du compte lorsque la restriction est détectée.

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

Action : connectez-vous à Facebook, cliquez sur votre photo de profil (en haut à droite), ouvrez la section Help et sélectionnez Account Status. L’assistant de support de Meta y affiche la raison spécifique de la restriction et vous permet de faire appel. Comme la restriction est appliquée par Meta au niveau du compte, ce code est non réessayable — ne construisez pas de logique de retry automatique autour ; résolvez d’abord la restriction avec Meta.

Erreurs de conversion de format d’image

Ayrshare convertit automatiquement les images WebP, HEIC et AVIF en JPEG avant la publication sur les plateformes qui ne les acceptent pas (Instagram, LinkedIn, TikTok, Google My Business, Threads et Snapchat pour WebP ; toutes les plateformes pour HEIC et AVIF). La conversion s’exécute de manière transparente au moment de l’envoi. Les trois erreurs ci-dessous ne surviennent que lorsque le pipeline de conversion lui-même ne peut pas aboutir ; si l’image source est déjà dans un format pris en charge, aucune conversion n’est tentée et ces codes n’apparaîtront pas. Code 450 — Image Format Conversion Failed (HTTP 400) L’image a été téléchargée mais n’a pas pu être ré-encodée en JPEG. Les causes les plus courantes sont un fichier source corrompu, un format interne inattendu à l’intérieur du conteneur, ou une image dépassant le plafond de taille pour la conversion.

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

Action : ouvrez le mediaUrl source directement dans un navigateur pour confirmer qu’il s’affiche. Si oui, réexportez l’image en JPEG ou PNG propre et réessayez la publication. Code 451 — Image Download Failed for Conversion (HTTP 400) Le pipeline de conversion n’a pas pu récupérer l’image source. Les causes typiques incluent une réponse 4xx/5xx de l’origine, un délai réseau dépassé, une chaîne de redirections dépassant la limite de sauts, ou une URL résolvant vers une adresse non publique (bloquée par le garde-fou SSRF). Le champ details, lorsqu’il est présent, contient la chaîne de cause sous-jacente.

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

Action : confirmez que le mediaUrl est publiquement accessible (pas d’authentification, pas de blocages robots.txt, résout via HTTPS). Si l’URL redirige, assurez-vous que la destination finale est également publique et non sur un réseau privé. Code 452 — Converted Image Upload Failed (HTTP 500) La conversion a réussi mais Ayrshare n’a pas pu placer le JPEG converti dans son bucket de stockage temporaire. Il s’agit d’une défaillance interne côté Ayrshare et elle est réessayable.

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

Action : réessayez la publication. Si l’erreur persiste sur plusieurs tentatives, contactez le support avec le mediaUrl et l’horodatage approximatif.

Erreurs transitoires de téléversement YouTube

Les codes d’erreur suivants fournissent des signaux spécifiques pour les échecs de téléversement YouTube qui sont typiquement transitoires et peuvent être réessayés sans risque. Les deux réponses incluent retryAvailable: true, de sorte que les intégrations peuvent brancher sur ce booléen plutôt que sur le code de statut HTTP. La plupart des anciennes réponses code: 176 pour les téléversements YouTube passent désormais par 453 (timeout transitoire) ou 454 (service temporairement indisponible), toutes deux avec retryAvailable: true. Si votre intégration filtre sur HTTP 500 pour réessayer les téléversements YouTube, passez au filtrage sur le champ retryAvailable du corps de la réponse. Code 453 — YouTube Upload Timed Out (HTTP 504) Renvoyé lorsque le pipeline d’ingestion YouTube de Google a dépassé son délai en acceptant le téléversement. C’est généralement transitoire et se résout de soi-même en une minute ou deux.

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

Action : réessayez la publication après 1 à 2 minutes avec un backoff exponentiel. Branchez sur le champ retryAvailable du corps de la réponse plutôt que sur le statut HTTP pour détecter les échecs réessayables. Vous pouvez utiliser l’endpoint retry post pour resoumettre la même charge utile. Code 454 — YouTube Upload Service Temporarily Unavailable (HTTP 503) Renvoyé lorsque l’endpoint de téléversement YouTube renvoie un statut 5xx, ou lorsque la connexion à YouTube a été réinitialisée ou expirée au niveau socket (ECONNRESET, ETIMEDOUT, ESOCKETTIMEDOUT). Ces conditions sont transitoires.

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

Action : réessayez la publication avec un backoff exponentiel. Branchez sur le champ retryAvailable du corps de la réponse plutôt que sur le statut HTTP pour détecter les échecs réessayables. Vous pouvez utiliser l’endpoint retry post pour resoumettre la même charge utile.

Erreurs de miniature YouTube - Code 307

Le code 307 est renvoyé lorsqu’une miniature personnalisée YouTube (thumbNail) ne peut pas être appliquée. Lorsque la vidéo elle-même est publiée avec succès, cela ne fait pas échouer la publication — le résultat YouTube conserve status: "success" et l’échec est signalé de manière additive dans un tableau warnings (feature: "thumbnail", code: 307). Le sous-objet thumbnail hérité est conservé pour la rétrocompatibilité. La cause la plus courante est une chaîne YouTube non vérifiée. Lorsqu’une chaîne n’a pas effectué la vérification par téléphone, YouTube renvoie un 403 en amont avec le message générique "The authenticated user doesn't have permissions to upload and set custom video thumbnails". Cette formulation ressemble à un problème OAuth, mais en pratique c’est presque toujours un problème de vérification, donc vérifiez d’abord la chaîne. La reconnexion du compte YouTube est une cause secondaire.

{
  "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 valide également la miniature avant publication lorsque cela est possible : le fichier doit être un PNG ou JPG/JPEG, faire 2 Mo ou moins et être servi depuis une URL accessible. Un problème de miniature ne fait jamais échouer la publication — la vidéo est toujours publiée et l’échec est toujours signalé comme une entrée non fatale dans warnings (le status de niveau supérieur reste "success"). Cela est vrai quel que soit le moment où le problème est détecté :

Détecté avant le téléversement. Lorsque la validation pré-publication peut affirmer de manière définitive que la miniature est invalide (mauvais type de fichier, taille supérieure à 2 Mo confirmée ou URL inaccessible), Ayrshare ignore la miniature, publie tout de même la vidéo et signale la raison précise dans warnings — vous évitez ainsi une tentative de téléversement vouée à l’échec et obtenez un message plus clair que celui que le fournisseur renverrait.
Détecté après le téléversement. Lorsque l’échec n’est détectable qu’une fois que YouTube traite la requête (par exemple le 403 de chaîne non vérifiée, ou un 413 pour une image trop volumineuse), la vidéo est déjà en ligne et l’échec est signalé dans le même tableau warnings.

Dans tous les cas, la réponse ressemble à l’exemple status: "success" + warnings montré plus haut dans cette section. Action : vérifiez votre chaîne YouTube sur https://www.youtube.com/verify (vérification par téléphone). Si votre chaîne est déjà vérifiée et que les miniatures échouent toujours, déconnectez et reconnectez votre compte YouTube dans Social Accounts et accordez toutes les autorisations. Voir YouTube Thumbnail Not Applied (Unverified Channel) pour le guide de dépannage complet.

Erreurs de publication Reddit

Code 442 — Reddit Banned Subreddit (HTTP 400) Renvoyé lorsque le compte a été banni de la publication dans le subreddit cible. Cela n’est pas réessayable — la publication n’aboutira pas si elle est resoumise en l’état. Le message inclut le nom du subreddit affecté (par exemple, r/news).

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

Action : retirez le subreddit banni de vos subreddits cibles. Réessayer la publication inchangée n’aboutira pas. Code 443 — Reddit Disallowed Word in Title (HTTP 400) Renvoyé lorsqu’un subreddit rejette la publication parce que son titre contient un mot interdit. Modifiez le titre avant de réessayer — la resoumettre en l’état n’aboutira pas. Le message inclut le nom du subreddit affecté (par exemple, r/news).

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

Action : modifiez le titre de la publication pour retirer le mot interdit, puis réessayez.

Erreurs de modération

Code 438 — Moderation Input Rejected (HTTP 400) Renvoyé par POST /validate/moderation lorsque le fournisseur d’IA rejette l’entrée fournie — par exemple, un type de fichier non pris en charge. Il s’agit d’un problème d’entrée de la requête, et non d’un échec de traitement transitoire.

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

Action : vérifiez que l’entrée de modération est valide et utilise un type de fichier pris en charge, puis resoumettez.

Contrastez le code 438 avec le code 331. Le code 331 couvre le même scénario de modération mais représente un véritable échec de traitement côté fournisseur (HTTP 500, message « There was an issue with the AI processing. Please try again. »). Le code 331 est un échec transitoire côté serveur que vous pouvez réessayer, tandis que le code 438 indique que l’entrée elle-même a été rejetée et doit être corrigée avant de réessayer.

Erreurs de statistiques LinkedIn

Code 475 — Re-link LinkedIn Profile for Analytics (HTTP 403) Renvoyé par POST /analytics/post et POST /analytics/social pour un profil LinkedIn personnel (membre) qui a été connecté avant la mise en service des statistiques membres. Ces profils manquent des scopes de statistiques membre LinkedIn (r_member_postAnalytics, r_member_profileAnalytics), donc LinkedIn rejette la requête de statistiques. La publication n’est pas affectée.

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

Action : demandez au propriétaire du compte de reconnecter son profil LinkedIn dans Social Accounts pour accorder les nouveaux scopes de statistiques, puis réessayez la requête de statistiques. Après la reconnexion, laissez quelques minutes avant que l’erreur ne disparaisse : Ayrshare met brièvement en cache cette erreur et LinkedIn met également en cache les autorisations du token, donc un profil reconnecté peut continuer à renvoyer le code 475 pendant environ 5 à 10 minutes avant que les statistiques ne fonctionnent.

Erreurs de commentaires TikTok

Code 288 — TikTok Comment Deferred / Post Still Processing (HTTP 400) TikTok traite les vidéos de manière asynchrone, de sorte que l’id d’une publication récemment publiée est "pending" jusqu’à ce que le webhook post.publish.publicly_available de TikTok résolve le véritable id de vidéo. Une requête get-comments, commentaire ou réponse contre une publication encore en cours de traitement (ou dont l’id est "failed") est refusée avant tout appel à TikTok et renvoie le code 288 au lieu d’un échec générique.

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

Action : attendez que TikTok termine son traitement, puis réessayez. Écoutez le webhook tikTokPublished Scheduled Action ou interrogez /history jusqu’à ce que l’id de la publication soit l’id numérique de vidéo résolu. Un first comment est publié automatiquement une fois la publication résolue, il n’a donc pas besoin d’être réessayé. Pour une publication "failed", le message indique à la place que la vidéo n’a pas pu être publiée et que l’action ne sera pas exécutée.

Traduction du message d’erreur

Le message d’erreur renvoyé par l’API peut être automatiquement traduit dans la langue de votre choix. C’est utile si vous souhaitez afficher l’erreur directement à votre utilisateur dans sa langue préférée. Voir ici si vous souhaitez choisir la langue de la page de connexion sociale. Dans l’en-tête, incluez :

"Translate-Error-Message": "Language_Code"

Où le Language_Code est l’un des codes de langue disponibles. Par exemple, ce qui suit traduira l’erreur en français.

"Translate-Error-Message": "fr" // Translate to French

Notre système détectera automatiquement la langue du message d’erreur.

​Gestion des erreurs

​Codes d’erreur spécifiques à Instagram

​Retry Available

​Erreurs BYO Key X/Twitter

​Erreurs d’amélioration de légende

​Erreurs de récupération de média / d’accès du crawler

​Limite de débit des statistiques Facebook

​Vérification d’identité Meta

​Restriction de compte Facebook

​Erreurs de conversion de format d’image

​Erreurs transitoires de téléversement YouTube

​Erreurs de miniature YouTube - Code 307

​Erreurs de publication Reddit

​Erreurs de modération

​Erreurs de statistiques LinkedIn

​Erreurs de commentaires TikTok

​Traduction du message d’erreur

Gestion des erreurs

Codes d’erreur spécifiques à Instagram

Retry Available

Erreurs BYO Key X/Twitter

Erreurs d’amélioration de légende

Erreurs de récupération de média / d’accès du crawler

Limite de débit des statistiques Facebook

Vérification d’identité Meta

Restriction de compte Facebook

Erreurs de conversion de format d’image

Erreurs transitoires de téléversement YouTube

Erreurs de miniature YouTube - Code 307

Erreurs de publication Reddit

Erreurs de modération

Erreurs de statistiques LinkedIn

Erreurs de commentaires TikTok

Traduction du message d’erreur