> ## 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. # Коди помилок Ayrshare > Специфічні коди помилок, що повертає Ayrshare. REST API включатиме відповідь зі списком помилок, якщо це застосовно. Помилки мають повернений код статусу 400, 401, 402, 403, 404, 429, 500, 502, 503 або 504. Успіх має повернений код статусу 200. Дивіться [тут](/errors/errors-http) для деталей. Кожен виклик API може повертати різні помилки залежно від конкретного запиту та будь-яких проблем, що виникли у соціальній мережі. Відповідь про помилку міститиме деталі про те, що пішло не так під час виклику API. Наприклад, публікація, яка вважається дублікатом у Twitter та Facebook, поверне таку відповідь. ```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" } ``` Зверніть увагу: ### Обробка помилок Ви повинні обробляти будь-які відповіді про помилки та вживати відповідних дій. Помилка сталася, якщо: Наприклад, якщо посилання Facebook було видалено Вашим користувачем — він змінив свій пароль або видалив доступ Ayrshare — під час публікації станеться така відповідь з кодом відповіді `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" } ``` Дією може бути повідомлення Вашого користувача через Вашу панель, SMS або електронну пошту. Інший приклад: якщо опубліковане зображення Instagram має неправильні розміри або співвідношення сторін з кодом відповіді `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?" } ``` Дією може бути повторне надсилання зображень з правильним співвідношенням сторін. ### Специфічні для Instagram коди помилок Наступні коди помилок надають конкретні деталі про збої публікації в Instagram, замінюючи загальну помилку 138, де це можливо. **Code 435 — Instagram Rate Limit (HTTP 429)** Професійні (Business / Creator) облікові записи Instagram підпадають під ліміт 50 публікацій протягом 24-годинного вікна в Meta's [Content Publishing API](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/content_publishing_limit/) (особисті облікові записи взагалі не можуть публікувати через API, тому ніколи не досягають цього ліміту). Коли ліміт перевищено, Meta повертає помилку rate-limit. Ayrshare також повертає `code: 435`, коли ендпоінт публікації Meta безпосередньо повертає HTTP 429 або коли базовий підкод помилки (`1390008`) вказує на throttle публікації / коментаря. ```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" } ] } ``` **Дія:** Зачекайте на скидання вікна rate limit перед повторною спробою. Коли Meta надає заголовок `Retry-After`, значення (у секундах) передається в полі `details` — зачекайте принаймні стільки часу перед повторним надсиланням. **Code 436 — Instagram Media Processing Timeout (HTTP 400)** Instagram надто довго обробляв завантажені медіа. Це може статися з великими відеофайлами або в періоди високого навантаження на сервери 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" } ] } ``` **Дія:** Повторіть публікацію, використовуючи ендпоінт [retry post](/apis/post/retry-post). Якщо проблема не зникає, спробуйте зменшити розмір медіафайлу. **Code 447 — Instagram Trial Reels: Missing graduationStrategy (HTTP 400)** Повертається, коли `instagramOptions.trialParams` надано у запиті [`/post`](/apis/post/post), але `graduationStrategy` відсутнє, `null` або порожній рядок. Trial reels вимагають явної стратегії випуску — дивіться [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" } ] } ``` **Дія:** Встановіть `instagramOptions.trialParams.graduationStrategy` на `"MANUAL"` або `"SS_PERFORMANCE"` і повторіть спробу, або видаліть `trialParams`, якщо Ви не мали намір публікувати trial reel. **Code 448 — Instagram Trial Reels: Invalid graduationStrategy (HTTP 400)** Повертається, коли `graduationStrategy` присутнє, але не точно `"MANUAL"` або `"SS_PERFORMANCE"`. Перевірка чутлива до регістру — значення на кшталт `"manual"` або `"ss_performance"` відхиляються. Поле `details` повторює відхилений ввід (усічений до 64 символів) для полегшення налагодження. ```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" } ] } ``` **Дія:** Надішліть `graduationStrategy` точно як `"MANUAL"` або `"SS_PERFORMANCE"` (верхній регістр, тип string). **Code 449 — Instagram Trial Reels: Incompatible Media (HTTP 400)** Повертається, коли медіа або форма публікації не має права на trial reel. Trial reels мають бути одним `.mp4` або `.mov` відео — каруселі (більше ніж один URL), stories (`instagramOptions.stories: true`) та не-відеорозширення всі відхиляються. Поле `details` уточнює, який саме підвипадок спрацював. ```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" } ] } ``` **Дія:** Надішліть один URL відео `.mp4` або `.mov` без прапорця `stories: true`. Видаліть додаткові записи `mediaUrls` або видаліть `trialParams`, якщо мали намір створити звичайну карусель / stories публікацію. **Code 258 — Instagram Account-State Error (HTTP 400)** Загальний збій стану облікового запису Instagram з базовим повідомленням "Error with Instagram." Це з'являється, коли Meta відхиляє запит через стан підключеного облікового запису Instagram, а не через вміст публікації. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 258, "message": "Error with Instagram.", "platform": "instagram" } ] } ``` Коли базовий Meta `error_subcode` — це `2207085`, відповідь додатково встановлює `relink: true` та `retryAvailable: true`, а повідомлення інструктує користувача відв'язати та повторно прив'язати обліковий запис Instagram, надавши всі дозволи: ```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" } ] } ``` **Дія:** Для підвипадку `2207085` запропонуйте користувачу відв'язати та повторно прив'язати свій обліковий запис Instagram у [Social Accounts](https://app.ayrshare.com/social-accounts), надавши всі запитувані дозволи, потім повторіть публікацію. Для інших помилок стану облікового запису перевірте, чи обліковий запис Instagram у нормальному стані в Meta, та повторіть спробу. #### Retry Available Іноді у соціальних мереж виникають невиправні помилки, наприклад, проблеми з серверами, і виклик зрештою зазнає невдачі навіть після численних повторних спроб. У цих випадках наша система визначить, чи можна повторити помилку, і якщо так, поле `retryAvailable` буде `true`. ```json theme={"system"} { "retryAvailable": true } ``` Потім Ви можете повторити виклик з тим самим payload. Якщо це публікація, Ви можете використати ендпоінт [retry post](/apis/post/retry-post). ### Помилки X/Twitter BYO Key Наступні коди помилок специфічні для операцій X/Twitter BYO (Bring Your Own) key: **Code 272 - Failed to Verify BYO Twitter Identity (HTTP 400)** Ayrshare не зміг підтвердити Вашу особу X/Twitter, використовуючи Ваші BYO consumer keys та OAuth-токени, збережені під час прив'язки. Форма відповіді відрізняється залежно від того, який виклик її викликав; обидві форми відповідають одним і тим самим трьом підвипадкам нижче. Перевірте, який з них застосовний, увійшовши на [x.com](https://x.com) з обліковим записом, який володіє BYO Developer App. Шлях публікації видає мінімальну відповідь: ```json theme={"system"} { "status": "error", "code": 272, "message": "Failed to verify BYO Twitter identity", "platform": "twitter" } ``` Шлях аналітики видає довше, самодокументоване повідомлення і може включати поле `details`, що містить необроблений рядок помилки 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" } ``` За наявності `details` віддзеркалює підказку з боку X і є найнадійнішим сигналом для того, який з підвипадків нижче застосовний. **Обліковий запис заблоковано.** Вхід на x.com показує повідомлення про блокування. **Дія:** Зверніться до підтримки X. Повторна прив'язка не відновить доступ, доки X не поновить обліковий запис. **Обліковий запис заблоковано (locked).** Вхід на x.com пропонує розблокувати завдання (CAPTCHA, верифікація телефоном тощо). **Дія:** Виконайте завдання розблокування на x.com, потім повторіть запит. Повторна прив'язка не потрібна. **Невідповідність особи або ключа.** Ваш обліковий запис X у нормальному стані на x.com, але Ваші BYO consumer keys належать до іншого X Developer App, ніж OAuth-токени, збережені під час прив'язки. **Дія:** Повторно прив'яжіть X у Social Accounts та авторизуйтесь тим самим обліковим записом X, який володіє BYO Developer App. **Code 416 — X Credits Depleted (HTTP 402)** На Вашому обліковому записі X Developer немає завантажених API-кредитів. Усі виклики X API вимагають кредитів. ```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" } ``` **Дія:** Перейдіть на [console.x.com](https://console.x.com) → Billing → Credits і придбайте кредити. Навіть \$5 достатньо для сотень API-викликів. **Code 417 — OAuth 1.0a App Permissions (HTTP 403)** Ваш X Access Token не має правильних дозволів для запитуваної операції. ```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" } ``` Ви також можете побачити заголовок відповіді `x-access-level: read`, який підтверджує, що Ваш Access Token був згенерований з дозволами лише для читання. **Дія:** У X Developer Console оновіть дозволи Вашого застосунку на **Read and write and Direct message**, потім регенеруйте свій Access Token у розділі Keys and tokens. Новий токен успадкує оновлені дозволи. Дивіться [X BYO Key Setup Guide](/dashboard/connect-social-accounts/x-twitter-byo-keys#troubleshooting) для деталей. **Code 419 - Missing BYO Credentials (HTTP 400)** Операції X/Twitter вимагають BYO API-облікових даних у заголовках запиту. Ayrshare повертає code 419, коли обидва заголовки відсутні, а також коли присутній лише один з пари. Рядок `message` варіюється залежно від того, який заголовок(и) відсутній. Коли `X-Twitter-OAuth1-Api-Key` та `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" } ``` Коли присутній лише один з пари (наприклад, key без 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" } ``` **Дія:** Надсилайте обидва `X-Twitter-OAuth1-Api-Key` та `X-Twitter-OAuth1-Api-Secret` у кожному X-запиті. Якщо Ви надаєте один без іншого, запит відхиляється з тим самим кодом. Дивіться [X BYO Keys Header Reference](/dashboard/connect-social-accounts/x-twitter-byo-keys#header-reference) для повного списку заголовків. **Code 423 — Legacy X/Twitter OAuth No Longer Supported (HTTP 403)** Повертається, коли запит X/Twitter покладається на застарілий (не-BYO) шлях OAuth, який більше не підтримується. Доступ до X API тепер вимагає Ваших власних облікових даних X Developer App, наданих через заголовки запиту. ```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" } ``` **Дія:** Налаштуйте X Developer App і надсилайте заголовки `X-Twitter-OAuth1-Api-Key` та `X-Twitter-OAuth1-Api-Secret` у кожному X-запиті. Дивіться [X BYO Key Setup Guide](/dashboard/connect-social-accounts/x-twitter-byo-keys) для повних кроків налаштування. ### Помилки Caption Enhancement **Code 441 — Caption Enhancement Failed (HTTP 502)** Повертається, коли розширення підпису (наприклад, [`shortenLinks`](/apis/post/post)) не вдається для однієї або кількох платформ під час підготовки публікації. Кожна уражена платформа з'являється в масиві `errors` з `source: "handlePostAdditions"` та `code: 441`. Коли не вдається лише для деяких платформ, інші платформи все одно публікуються успішно, і їхні результати з'являються в `postIds`. У цьому випадку `status` верхнього рівня — `"error"`, але `postIds` непорожній — клієнти повинні розглядати `status` та `errors[]` як взаємодоповнюючі, а не взаємовиключні. ```json theme={"system"} { "status": "error", "errors": [ { "platform": "twitter", "status": "error", "source": "handlePostAdditions", "code": 441, "message": "Caption enhancement failed for twitter. . Post was not sent to this platform." } ], "postIds": [ { "status": "success", "id": "...", "postUrl": "...", "platform": "bluesky" } ], "id": "..." } ``` Якщо **всі** платформи зазнають невдачі під час розширення, відповідь буде верхнього рівня `code: 441` з HTTP `502` і публікація не створюється: ```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. " } ] } ``` **Дія:** Збої caption enhancement зазвичай є тимчасовими (базовий сервіс скорочення або розширення повернув помилку). * **Якщо `postIds` непорожній** (деякі платформи опублікувались успішно), **не** повторно надсилайте повний набір платформ — це б дублювало публікацію на успішних платформах. Натомість перевірте `errors[]`, щоб визначити невдалі платформи, і повторіть запит лише з ними, або покладіться на власний ідемпотентний потік повторення. * **Якщо `postIds` порожній або відсутній** (повний збій під час планування/публікації), безпечно повторіть повний запит. * Якщо збій зберігається, надішліть публікацію без прапорця розширення (наприклад, видаліть `shortenLinks`) або зверніться до підтримки. ### Помилки Media Fetch / Crawler Access **Code 440 — Social Network Could Not Download Media (HTTP 400)** Повертається, коли краулер публікації платформи не може завантажити наданий Вами `mediaUrl` — найчастіше через те, що `robots.txt` або правило WAF / bot-fight блокує краулер (наприклад, `facebookexternalhit` від Meta). Рядок `details` надходить від upstream-платформи і часто є текстом помилки Meta/Instagram 2207052. ```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": "..." } ``` **Code 138 — Instagram Media Fetch Blocked (HTTP 400)** Резервний код для збоїв media-fetch Instagram, коли upstream-відповідь менш специфічна, ніж та, що викликає code 440. Рядок `details` зазвичай містить `"Restricted by robots.txt"` або `"HTTP error code 403"`. Code 138 також використовується для проблем із співвідношенням сторін / форматом та інших загальних помилок Instagram, тому варіант media-fetch можна ідентифікувати за рядком `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": "..." } ``` **Code 379 — Threads Posting Error** Повертається, коли публікація в Threads зазнає невдачі. Найчастіше спричинена тією ж проблемою media-fetch, що й коди 440 / 138, при публікації на обидві платформи з тим самим `mediaUrl`. Threads API не повертає рядки з деталями, тому діагностика зазвичай вимагає перевірки супутньої помилки Instagram 440 або 138 у тій самій публікації. ```json theme={"system"} { "status": "error", "errors": [{ "status": "error", "code": 379, "message": "Error posting to Threads.", "action": "post", "platform": "threads" }], "postIds": [], "id": "..." } ``` **Дія:** Дивіться [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) для повного вирішення проблем, включно з фрагментами `robots.txt` та командою перевірки. ### Facebook Analytics Rate Limit **Code 444 — Facebook Page Analytics Rate Limit (HTTP 429)** Повертається, коли сторінка Facebook перевищила ліміт запитів Meta для сторінки на аналітичному ендпоінті. Базова помилка Meta — `80001` ("There have been too many calls to this Page account."). Сторінка залишається прив'язаною, і публікації продовжують працювати — throttling обмежує лише розповсюдження аналітики для цієї сторінки. Коли throttle виявлено для однієї публікації у відповіді [`/history/facebook`](/apis/history/history-platform) або [analytics](/apis/analytics/social), кожна уражена публікація містить `code: 444` в `facebook.code` з `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": "..." } ``` **Дія:** Зачекайте кілька хвилин і повторіть спробу. Вікно rate-limit Meta зазвичай вирішується протягом години без жодних дій з боку сторінки. **Не** пропонуйте користувачу повторно прив'язувати обліковий запис — це тимчасовий throttle з боку Meta, а не збій авторизації. Якщо Ви раніше обробляли цей стан як `code: 161` ("Facebook authorization error … unlink and re-link"), оновіть свою інтеграцію, щоб розпізнавати `code: 444` і повторювати з backoff замість ініціювання потоку повторної прив'язки. Класифікацію `161` було виправлено у квітні 2026 року. ### Meta Identity Verification **Code 326 — Meta Identity Verification Required (HTTP 403)** Повертається, коли Meta вимагає додаткову верифікацію особи для підключеного облікового запису, перш ніж прийняти запит. Це стосується всіх платформ Meta — Facebook, Instagram, Facebook Groups, Threads та Messenger. Повторне підключення облікового запису **не** вирішує цю проблему; верифікація має бути завершена на боці 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" } ] } ``` **Дія:** Нехай власник облікового запису завершить верифікацію особи Meta на [Meta Business Support](https://www.facebook.com/business-support-home), потім повторіть запит. **Не** пропонуйте користувачу повторно прив'язувати обліковий запис — повторна прив'язка не зніме цю вимогу. ### Facebook Account Restriction **Code 476 — Facebook Account Restriction (HTTP 400)** Повертається, коли публікація в Facebook зазнає невдачі, оскільки Meta наклала обмеження на обліковий запис (підкоди помилки Meta `2424009` та `1404078`, або формулювання обмеження Meta, коли помилка не містить підкоду). Це обмеження на рівні облікового запису, а не тимчасова проблема публікації — воно **не підлягає повторному виконанню** і **не** містить прапорця `retryAvailable`. Повторне надсилання тієї ж публікації не буде успішним, доки обмеження не буде вирішено з Meta. Обліковий запис залишається прив'язаним до Ayrshare; повторна прив'язка не потрібна. Meta не повертає конкретну причину обмеження через API, тому клієнт має перевірити сторінку Account Status Meta безпосередньо, щоб побачити причину та оскаржити. Коли Meta надає власний дослівний текст, Ayrshare відображає його у полі `details`. Ayrshare також надсилає власнику облікового запису повідомлення електронною поштою, коли виявлено обмеження. ```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" } ] } ``` **Дія:** Увійдіть у Facebook, натисніть на своє зображення профілю (справа вгорі), відкрийте розділ Help та виберіть **Account Status**. Асистент підтримки Meta там показує конкретну причину обмеження та дозволяє оскаржити. Оскільки обмеження застосовується Meta на рівні облікового запису, цей код не підлягає повторному виконанню — не будуйте автоматичну логіку повторення навколо нього; спершу вирішіть обмеження з Meta. ### Помилки Image Format Conversion Ayrshare автоматично конвертує WebP, HEIC та AVIF-зображення у JPEG перед публікацією на платформах, які їх не приймають (Instagram, LinkedIn, TikTok, Google My Business, Threads та Snapchat для WebP; усі платформи для HEIC та AVIF). Конвертація виконується прозоро під час надсилання. Три помилки нижче спрацьовують лише тоді, коли сам конвеєр конвертації не може завершитись; якщо вихідне зображення вже у підтримуваному форматі, конвертація не виконується, і ці коди не з'являться. **Code 450 — Image Format Conversion Failed (HTTP 400)** Зображення завантажене, але не може бути перекодоване у JPEG. Найпоширенішими причинами є пошкоджений вихідний файл, неочікуваний внутрішній формат всередині контейнера або зображення, що перевищує ліміт розміру конвертації. ```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" } ] } ``` **Дія:** Відкрийте вихідний `mediaUrl` безпосередньо у браузері, щоб переконатися, що він відображається. Якщо так, повторно експортуйте зображення у чистий JPEG або PNG і повторіть публікацію. **Code 451 — Image Download Failed for Conversion (HTTP 400)** Конвеєр конвертації не зміг отримати вихідне зображення. Типові причини включають відповідь 4xx/5xx від origin, тайм-аут мережі, ланцюг перенаправлень, що перевищує ліміт стрибків, або URL, що розв'язується у непублічну адресу (заблокований захистом SSRF). Поле `details`, за наявності, містить рядок базової причини. ```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" } ] } ``` **Дія:** Переконайтеся, що `mediaUrl` публічно доступний (без auth, без блоків у `robots.txt`, розв'язується через HTTPS). Якщо URL перенаправляє, переконайтеся, що кінцева адреса також публічна і не знаходиться у приватній мережі. **Code 452 — Converted Image Upload Failed (HTTP 500)** Конвертація вдалася, але Ayrshare не зміг завантажити конвертований JPEG до свого тимчасового сховища. Це внутрішній збій з боку Ayrshare і його можна повторити. ```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" } ] } ``` **Дія:** Повторіть публікацію. Якщо помилка зберігається після кількох повторень, зверніться до підтримки з `mediaUrl` та приблизною часовою міткою. ### Тимчасові помилки завантаження YouTube Наступні коди помилок надають конкретні сигнали для збоїв завантаження YouTube, які зазвичай є тимчасовими та безпечними для повторення. Обидві відповіді містять `retryAvailable: true`, тому інтеграції можуть галузитись за цим boolean, а не за кодом HTTP-статусу. Більшість попередніх відповідей `code: 176` для завантажень YouTube тепер маршрутизуються до **453** (тимчасовий тайм-аут) або **454** (тимчасова недоступність сервісу), обидві з `retryAvailable: true`. Якщо Ваша інтеграція фільтрує за HTTP 500 для повторення завантажень YouTube, перейдіть на фільтрацію за полем `retryAvailable` у тілі відповіді. **Code 453 — YouTube Upload Timed Out (HTTP 504)** Повертається, коли конвеєр ingest YouTube від Google тайм-аутнув під час прийняття завантаження. Це зазвичай тимчасово і вирішується самостійно протягом хвилини або двох. ```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" } ] } ``` **Дія:** Повторіть публікацію через 1–2 хвилини з експоненційним backoff. Галузьтесь за полем `retryAvailable` у тілі відповіді, а не за HTTP-статусом, щоб виявити збої, які можна повторити. Ви можете використати ендпоінт [retry post](/apis/post/retry-post) для повторного надсилання того ж payload. **Code 454 — YouTube Upload Service Temporarily Unavailable (HTTP 503)** Повертається, коли ендпоінт завантаження YouTube повертає статус 5xx, або коли з'єднання з YouTube було скинуто чи тайм-аутнуто на рівні сокета (`ECONNRESET`, `ETIMEDOUT`, `ESOCKETTIMEDOUT`). Ці стани тимчасові. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 454, "message": "YouTube upload service temporarily unavailable. Please retry.", "retryAvailable": true, "platform": "youtube" } ] } ``` **Дія:** Повторіть публікацію з експоненційним backoff. Галузьтесь за полем `retryAvailable` у тілі відповіді, а не за HTTP-статусом, щоб виявити збої, які можна повторити. Ви можете використати ендпоінт [retry post](/apis/post/retry-post) для повторного надсилання того ж payload. ### YouTube Thumbnail Errors Code 307 Code `307` повертається, коли спеціальний `thumbNail` YouTube не може бути застосовано. Коли саме відео публікується успішно, це **не** призводить до збою публікації — результат YouTube зберігає `status: "success"` і додатково відображає збій у масиві `warnings` (`feature: "thumbnail"`, `code: 307`). Старий підоб'єкт `thumbnail` зберігається для зворотної сумісності. Найпоширеніша причина — **неверифікований канал YouTube**. Коли канал не завершив верифікацію телефоном, YouTube повертає upstream `403` із загальним повідомленням `"The authenticated user doesn't have permissions to upload and set custom video thumbnails"`. Це формулювання звучить як проблема OAuth, але на практиці це майже завжди проблема верифікації, тому спочатку перевіряйте канал. Повторна прив'язка облікового запису YouTube є другорядною причиною. ```json theme={"system"} { "status": "success", "id": "", "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": "" }, "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": "" } ] } ``` Ayrshare також валідує мініатюру перед публікацією там, де це можливо: файл має бути **PNG або JPG/JPEG**, **2 МБ або менше** і надаватися з **доступного URL**. Проблема з мініатюрою **ніколи не призводить до збою публікації** — відео завжди публікується, а збій завжди відображається як нефатальний запис `warnings` (`status` верхнього рівня залишається `"success"`). Це діє незалежно від того, коли виявлено проблему: * **Виявлено до завантаження.** Коли валідація перед публікацією може однозначно сказати, що мініатюра недійсна (неправильний тип файлу, підтверджений розмір понад 2 МБ або недоступний URL), Ayrshare пропускає мініатюру, все одно публікує відео та повідомляє точну причину в `warnings` — тому Ви уникаєте приреченої спроби завантаження та отримуєте чіткіше повідомлення, ніж повернув би провайдер. * **Виявлено після завантаження.** Коли збій можна виявити лише після обробки запиту YouTube (наприклад, `403` для неверифікованого каналу, або `413` для завеликого зображення), відео вже опубліковано, а збій відображається у тому ж масиві `warnings`. У будь-якому випадку відповідь виглядає як приклад `status: "success"` + `warnings`, показаний раніше в цьому розділі. **Дія:** Верифікуйте свій канал YouTube на [https://www.youtube.com/verify](https://www.youtube.com/verify) (верифікація телефоном). Якщо Ваш канал уже верифіковано, а мініатюри все одно не працюють, відв'яжіть та повторно прив'яжіть обліковий запис YouTube у [Social Accounts](https://app.ayrshare.com/social-accounts) і надайте всі дозволи. Дивіться [YouTube Thumbnail Not Applied (Unverified Channel)](/help-center/technical-support/youtube_thumbnail_unverified_channel) для повного посібника з вирішення проблем. ### Помилки публікації Reddit **Code 442 — Reddit Banned Subreddit (HTTP 400)** Повертається, коли обліковий запис було заблоковано від публікації у цільовому subreddit. Це **не** можна повторити — публікація не буде успішною, якщо повторно надіслати її як є. Повідомлення містить назву ураженого subreddit (наприклад, `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" } ] } ``` **Дія:** Видаліть заблокований subreddit зі своїх цільових subreddit. Повторення публікації без змін не буде успішним. **Code 443 — Reddit Disallowed Word in Title (HTTP 400)** Повертається, коли subreddit відхиляє публікацію через наявність у заголовку забороненого слова. Відредагуйте заголовок перед повторенням — повторне надсилання як є не буде успішним. Повідомлення містить назву ураженого subreddit (наприклад, `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" } ] } ``` **Дія:** Відредагуйте заголовок публікації, щоб видалити заборонене слово, потім повторіть. ### Помилки модерації **Code 438 — Moderation Input Rejected (HTTP 400)** Повертається [`POST /validate/moderation`](/apis/post/post), коли AI-провайдер відхиляє наданий ввід — наприклад, непідтримуваний тип файлу. Це проблема введення в запиті, а не тимчасовий збій обробки. ```json theme={"system"} { "status": "error", "errors": [ { "action": "moderation", "status": "error", "code": 438, "message": "There was an issue with the AI processing." } ] } ``` **Дія:** Перевірте, чи ввід модерації валідний та використовує підтримуваний тип файлу, потім повторно надішліть. Порівняйте code 438 з **code 331**. Code 331 охоплює той самий сценарій модерації, але представляє справжній збій обробки з боку провайдера (HTTP 500, повідомлення "There was an issue with the AI processing. Please try again."). Code 331 — це тимчасовий збій з боку сервера, який можна повторити, тоді як code 438 вказує, що сам ввід було відхилено і його потрібно виправити перед повторенням. ### Помилки аналітики LinkedIn **Code 475 — Re-link LinkedIn Profile for Analytics (HTTP 403)** Повертається [`POST /analytics/post`](/apis/analytics/post) та [`POST /analytics/social`](/apis/analytics/social) для особистого (member) профілю LinkedIn, який було прив'язано до випуску member analytics. Цим профілям бракує scope member analytics LinkedIn (`r_member_postAnalytics`, `r_member_profileAnalytics`), тому LinkedIn відхиляє запит аналітики. Публікація не зачіпається. ```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" } } ``` **Дія:** Нехай власник облікового запису повторно прив'яже свій профіль LinkedIn у [Social Accounts](https://app.ayrshare.com/social-accounts), щоб надати нові scope аналітики, потім повторіть запит аналітики. Після повторної прив'язки зачекайте кілька хвилин, поки помилка не зникне: Ayrshare кешує цю помилку ненадовго, і LinkedIn також кешує дозволи токена, тому повторно прив'язаний профіль може продовжувати повертати code `475` протягом приблизно 5-10 хвилин, перш ніж аналітика запрацює. ### Помилки коментарів TikTok **Code 288 — TikTok Comment Deferred / Post Still Processing (HTTP 400)** TikTok обробляє відео асинхронно, тож `id` свіжо опублікованої публікації — `"pending"`, поки webhook TikTok `post.publish.publicly_available` не розв'яже справжній id відео. Запит [get-comments](/apis/comments/get-comments), запит на коментар або відповідь для публікації, яка все ще обробляється (або тієї, чий `id` — `"failed"`), відхиляється до будь-якого виклику TikTok і повертає code 288 замість загального збою. ```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" } ] } ``` **Дія:** Зачекайте, поки TikTok завершить обробку, потім повторіть спробу. Слухайте [`tikTokPublished` Scheduled Action webhook](/apis/webhooks/actions#scheduled-action) або опитуйте [/history](/apis/history/overview), поки `id` публікації не буде розв'язаним числовим id відео. [First comment](/apis/post/overview#first-comment) публікується автоматично, коли публікація розв'язується, тому його не потрібно повторювати. Для публікації `"failed"` повідомлення натомість зазначає, що відео не вдалося опублікувати, і дія не запуститься. ### Переклад повідомлень про помилки Відповідь із повідомленням про помилку API можна автоматично перекладати мовою на Ваш вибір. Це корисно, якщо Ви хочете показати помилку безпосередньо Вашому користувачу його бажаною мовою. Дивіться тут, якщо Ви хочете [обрати мову сторінки прив'язки соціальних мереж](/multiple-users/manage-user-profiles#set-language-for-the-social-linking-page). У заголовок включіть: ```json theme={"system"} "Translate-Error-Message": "Language_Code" ``` Де `Language_Code` — це один з доступних[ мовних кодів](/iso-codes/language). Наприклад, наступне перекладе помилку французькою. ```json theme={"system"} "Translate-Error-Message": "fr" // Translate to French ``` Наша система автоматично визначить мову повідомлення про помилку.