Помилки мають повернений код статусу 400, 401, 402, 403, 404, 429, 500, 502, 503 або 504. Успіх має
повернений код статусу 200. Дивіться тут для деталей.
- Поле
errorsмістить масив помилок, по одній на кожну соціальну мережу, у якій сталася помилка. actionпосилається на тип поверненої помилки.- Поле
statusверхнього рівня буде “error”, якщо виклик API зазнав невдачі. Наприклад, для виклику /post, якщо всі публікації в соціальні мережі були успішними, полеstatusбуде “success”, інакше поле статусу буде “error”. - Поле
codeмістить довідковий код помилки Ayrshare. - Поле
message— це специфічні деталі помилки.
Обробка помилок
Ви повинні обробляти будь-які відповіді про помилки та вживати відповідних дій. Помилка сталася, якщо:- Код повернення відповіді не
200 - Статус JSON-відповіді —
error
400 Bad Request.
400 Bad Request:
Специфічні для Instagram коди помилок
Наступні коди помилок надають конкретні деталі про збої публікації в Instagram, замінюючи загальну помилку 138, де це можливо. Code 435 — Instagram Rate Limit (HTTP 429) Професійні (Business / Creator) облікові записи Instagram підпадають під ліміт 50 публікацій протягом 24-годинного вікна в Meta’s Content Publishing API (особисті облікові записи взагалі не можуть публікувати через API, тому ніколи не досягають цього ліміту). Коли ліміт перевищено, Meta повертає помилку rate-limit. Ayrshare також повертаєcode: 435, коли ендпоінт публікації Meta безпосередньо повертає HTTP 429 або коли базовий підкод помилки (1390008) вказує на throttle публікації / коментаря.
Retry-After, значення (у секундах) передається в полі details — зачекайте принаймні стільки часу перед повторним надсиланням.
Code 436 — Instagram Media Processing Timeout (HTTP 400)
Instagram надто довго обробляв завантажені медіа. Це може статися з великими відеофайлами або в періоди високого навантаження на сервери Meta.
instagramOptions.trialParams надано у запиті /post, але graduationStrategy відсутнє, null або порожній рядок. Trial reels вимагають явної стратегії випуску — дивіться Trial Reels.
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 символів) для полегшення налагодження.
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 уточнює, який саме підвипадок спрацював.
.mp4 або .mov без прапорця stories: true. Видаліть додаткові записи mediaUrls або видаліть trialParams, якщо мали намір створити звичайну карусель / stories публікацію.
Code 258 — Instagram Account-State Error (HTTP 400)
Загальний збій стану облікового запису Instagram з базовим повідомленням “Error with Instagram.” Це з’являється, коли Meta відхиляє запит через стан підключеного облікового запису Instagram, а не через вміст публікації.
error_subcode — це 2207085, відповідь додатково встановлює relink: true та retryAvailable: true, а повідомлення інструктує користувача відв’язати та повторно прив’язати обліковий запис Instagram, надавши всі дозволи:
2207085 запропонуйте користувачу відв’язати та повторно прив’язати свій обліковий запис Instagram у Social Accounts, надавши всі запитувані дозволи, потім повторіть публікацію. Для інших помилок стану облікового запису перевірте, чи обліковий запис Instagram у нормальному стані в Meta, та повторіть спробу.
Retry Available
Іноді у соціальних мереж виникають невиправні помилки, наприклад, проблеми з серверами, і виклик зрештою зазнає невдачі навіть після численних повторних спроб. У цих випадках наша система визначить, чи можна повторити помилку, і якщо так, полеretryAvailable буде true.
Помилки 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 з обліковим записом, який володіє BYO Developer App. Шлях публікації видає мінімальну відповідь:details, що містить необроблений рядок помилки X:
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 вимагають кредитів.
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 для деталей.
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 обидва відсутні:
X-Twitter-OAuth1-Api-Key та X-Twitter-OAuth1-Api-Secret у кожному X-запиті. Якщо Ви надаєте один без іншого, запит відхиляється з тим самим кодом. Дивіться X BYO Keys Header Reference для повного списку заголовків.
Code 423 — Legacy X/Twitter OAuth No Longer Supported (HTTP 403)
Повертається, коли запит X/Twitter покладається на застарілий (не-BYO) шлях OAuth, який більше не підтримується. Доступ до X API тепер вимагає Ваших власних облікових даних X Developer App, наданих через заголовки запиту.
X-Twitter-OAuth1-Api-Key та X-Twitter-OAuth1-Api-Secret у кожному X-запиті. Дивіться X BYO Key Setup Guide для повних кроків налаштування.
Помилки Caption Enhancement
Code 441 — Caption Enhancement Failed (HTTP 502) Повертається, коли розширення підпису (наприклад,shortenLinks) не вдається для однієї або кількох платформ під час підготовки публікації. Кожна уражена платформа з’являється в масиві errors з source: "handlePostAdditions" та code: 441.
Коли не вдається лише для деяких платформ, інші платформи все одно публікуються успішно, і їхні результати з’являються в postIds. У цьому випадку status верхнього рівня — "error", але postIds непорожній — клієнти повинні розглядати status та errors[] як взаємодоповнюючі, а не взаємовиключні.
code: 441 з HTTP 502 і публікація не створюється:
- Якщо
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.
details зазвичай містить "Restricted by robots.txt" або "HTTP error code 403". Code 138 також використовується для проблем із співвідношенням сторін / форматом та інших загальних помилок Instagram, тому варіант media-fetch можна ідентифікувати за рядком details.
mediaUrl. Threads API не повертає рядки з деталями, тому діагностика зазвичай вимагає перевірки супутньої помилки Instagram 440 або 138 у тій самій публікації.
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 або analytics, кожна уражена публікація містить code: 444 в facebook.code з errCode: 80001:
Meta Identity Verification
Code 326 — Meta Identity Verification Required (HTTP 403) Повертається, коли Meta вимагає додаткову верифікацію особи для підключеного облікового запису, перш ніж прийняти запит. Це стосується всіх платформ Meta — Facebook, Instagram, Facebook Groups, Threads та Messenger. Повторне підключення облікового запису не вирішує цю проблему; верифікація має бути завершена на боці Meta.Facebook Account Restriction
Code 476 — Facebook Account Restriction (HTTP 400) Повертається, коли публікація в Facebook зазнає невдачі, оскільки Meta наклала обмеження на обліковий запис (підкоди помилки Meta2424009 та 1404078, або формулювання обмеження Meta, коли помилка не містить підкоду). Це обмеження на рівні облікового запису, а не тимчасова проблема публікації — воно не підлягає повторному виконанню і не містить прапорця retryAvailable. Повторне надсилання тієї ж публікації не буде успішним, доки обмеження не буде вирішено з Meta. Обліковий запис залишається прив’язаним до Ayrshare; повторна прив’язка не потрібна.
Meta не повертає конкретну причину обмеження через API, тому клієнт має перевірити сторінку Account Status Meta безпосередньо, щоб побачити причину та оскаржити. Коли Meta надає власний дослівний текст, Ayrshare відображає його у полі details. Ayrshare також надсилає власнику облікового запису повідомлення електронною поштою, коли виявлено обмеження.
Помилки 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. Найпоширенішими причинами є пошкоджений вихідний файл, неочікуваний внутрішній формат всередині контейнера або зображення, що перевищує ліміт розміру конвертації.mediaUrl безпосередньо у браузері, щоб переконатися, що він відображається. Якщо так, повторно експортуйте зображення у чистий JPEG або PNG і повторіть публікацію.
Code 451 — Image Download Failed for Conversion (HTTP 400)
Конвеєр конвертації не зміг отримати вихідне зображення. Типові причини включають відповідь 4xx/5xx від origin, тайм-аут мережі, ланцюг перенаправлень, що перевищує ліміт стрибків, або URL, що розв’язується у непублічну адресу (заблокований захистом SSRF). Поле details, за наявності, містить рядок базової причини.
mediaUrl публічно доступний (без auth, без блоків у robots.txt, розв’язується через HTTPS). Якщо URL перенаправляє, переконайтеся, що кінцева адреса також публічна і не знаходиться у приватній мережі.
Code 452 — Converted Image Upload Failed (HTTP 500)
Конвертація вдалася, але Ayrshare не зміг завантажити конвертований JPEG до свого тимчасового сховища. Це внутрішній збій з боку Ayrshare і його можна повторити.
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 тайм-аутнув під час прийняття завантаження. Це зазвичай тимчасово і вирішується самостійно протягом хвилини або двох.
retryAvailable у тілі відповіді, а не за HTTP-статусом, щоб виявити збої, які можна повторити. Ви можете використати ендпоінт retry post для повторного надсилання того ж payload.
Code 454 — YouTube Upload Service Temporarily Unavailable (HTTP 503)
Повертається, коли ендпоінт завантаження YouTube повертає статус 5xx, або коли з’єднання з YouTube було скинуто чи тайм-аутнуто на рівні сокета (ECONNRESET, ETIMEDOUT, ESOCKETTIMEDOUT). Ці стани тимчасові.
retryAvailable у тілі відповіді, а не за HTTP-статусом, щоб виявити збої, які можна повторити. Ви можете використати ендпоінт retry post для повторного надсилання того ж payload.
YouTube Thumbnail Errors Code 307
Code307 повертається, коли спеціальний 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 є другорядною причиною.
warnings (status верхнього рівня залишається "success"). Це діє незалежно від того, коли виявлено проблему:
- Виявлено до завантаження. Коли валідація перед публікацією може однозначно сказати, що мініатюра недійсна (неправильний тип файлу, підтверджений розмір понад 2 МБ або недоступний URL), Ayrshare пропускає мініатюру, все одно публікує відео та повідомляє точну причину в
warnings— тому Ви уникаєте приреченої спроби завантаження та отримуєте чіткіше повідомлення, ніж повернув би провайдер. - Виявлено після завантаження. Коли збій можна виявити лише після обробки запиту YouTube (наприклад,
403для неверифікованого каналу, або413для завеликого зображення), відео вже опубліковано, а збій відображається у тому ж масивіwarnings.
status: "success" + warnings, показаний раніше в цьому розділі.
Дія: Верифікуйте свій канал YouTube на https://www.youtube.com/verify (верифікація телефоном). Якщо Ваш канал уже верифіковано, а мініатюри все одно не працюють, відв’яжіть та повторно прив’яжіть обліковий запис YouTube у Social Accounts і надайте всі дозволи. Дивіться YouTube Thumbnail Not Applied (Unverified Channel) для повного посібника з вирішення проблем.
Помилки публікації Reddit
Code 442 — Reddit Banned Subreddit (HTTP 400) Повертається, коли обліковий запис було заблоковано від публікації у цільовому subreddit. Це не можна повторити — публікація не буде успішною, якщо повторно надіслати її як є. Повідомлення містить назву ураженого subreddit (наприклад,r/news).
r/news).
Помилки модерації
Code 438 — Moderation Input Rejected (HTTP 400) ПовертаєтьсяPOST /validate/moderation, коли AI-провайдер відхиляє наданий ввід — наприклад, непідтримуваний тип файлу. Це проблема введення в запиті, а не тимчасовий збій обробки.
Порівняйте 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 та POST /analytics/social для особистого (member) профілю LinkedIn, який було прив’язано до випуску member analytics. Цим профілям бракує scope member analytics LinkedIn (r_member_postAnalytics, r_member_profileAnalytics), тому LinkedIn відхиляє запит аналітики. Публікація не зачіпається.
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, запит на коментар або відповідь для публікації, яка все ще обробляється (або тієї, чий id — "failed"), відхиляється до будь-якого виклику TikTok і повертає code 288 замість загального збою.
tikTokPublished Scheduled Action webhook або опитуйте /history, поки id публікації не буде розв’язаним числовим id відео. First comment публікується автоматично, коли публікація розв’язується, тому його не потрібно повторювати. Для публікації "failed" повідомлення натомість зазначає, що відео не вдалося опублікувати, і дія не запуститься.
Переклад повідомлень про помилки
Відповідь із повідомленням про помилку API можна автоматично перекладати мовою на Ваш вибір. Це корисно, якщо Ви хочете показати помилку безпосередньо Вашому користувачу його бажаною мовою. Дивіться тут, якщо Ви хочете обрати мову сторінки прив’язки соціальних мереж. У заголовок включіть:Language_Code — це один з доступних мовних кодів.
Наприклад, наступне перекладе помилку французькою.
