Instagram Graph API: ліміти, вебхуки й типові помилки (2026)

Instagram Graph API — це не «просте API для постів». Це шар над інфраструктурою Meta з жорсткими лімітами запитів, асинхронними вебхуками й токенами, які тихо помирають через 60 днів. Ми в MaxICo Labs зібрали з десятків інтеграцій (дашборди, боти, автопостинг, парсинг метрик) карту болю: де ламається найчастіше і як це лагодити. Це технічний розбір на 2026 рік — з таблицею кодів помилок, реальними цифрами лімітів і робочими патернами.

Що таке Instagram Graph API і чому воно складне

Плутанина №1: є Instagram Graph API (для Business/Creator акаунтів, через Facebook Page) і є Instagram API with Instagram Login (новіший, без обов'язкової Page). Більшість продакшн-інтеграцій досі йдуть через Graph API, прив'язаний до Facebook-сторінки та Business Portfolio.

Практичний висновок: перш ніж писати код, з'ясуйте, який саме flow вам потрібен. Дашборд аналітики — Graph API з instagram_manage_insights. Автовідповіді в директі — це вже Messaging API з окремими правами instagram_manage_messages і обов'язковими вебхуками. Помилка на цьому кроці коштує тижня переробок.

Базовий endpoint у 2026 — graph.facebook.com/v23.0/ (перевіряйте актуальну версію: Meta деприкейтить старі раз на ~2 роки). Кожен виклик — це GET/POST з access_token у query або в заголовку.

Ще один момент, який ламає новачків: майже все прив'язане до numeric IG User ID, а не до @username. Свій ID тягнете через GET /me/accounts → далі поле instagram_business_account. Чужий акаунт для аналітики (business discovery) — тільки за username через ваш власний акаунт: GET /{ig-user-id}?fields=business_discovery.username(competitor){followers_count,media_count}. Пряме звернення до @username як до ID дає помилку 803.

Rate limits: скільки насправді можна

Тут найбільше міфів. Instagram Graph API використовує модель Business Use Case (BUC) rate limits, а не простий «N запитів на хвилину».

Ключова формула для більшості Business-викликів:

Ліміт = 4800 × (кількість impressions акаунта за 24 год) звернень / 24 год

Тобто ліміт прив'язаний до розміру акаунта. Маленький акаунт (1000 impressions/добу) отримує принципово менше квоти, ніж великий. Плюс поверх цього діють:

Тип ліміту	Значення (орієнтир 2026)	Область дії
Platform rate limit (app-level)	200 × кількість користувачів / год	Увесь застосунок
BUC (Instagram)	4800 × impressions / 24 год	На акаунт
Content Publishing	100 постів / 24 год	На IG-акаунт
Messaging (директ)	залежить від вікна 24 год + якості	На розмову

Головна пастка: заголовок X-Business-Use-Case-Usage у відповіді. У ньому JSON з полями call_count, total_cputime, total_time (у відсотках від ліміту) і estimated_time_to_regain_access. Якщо ви не читаєте цей заголовок — ви не керуєте лімітами, ви їх ловите постфактум по 429.

Практичний патерн: після кожного батча запитів парсіть X-Business-Use-Case-Usage, і якщо будь-яке з call_count/total_cputime/total_time > 75% — вводьте exponential backoff і паузу. Не чекайте 100%: там уже блок на estimated_time_to_regain_access мілісекунд (інколи години).

Content Publishing має окремий ліміт

Публікація постів — окрема квота: 100 опублікованих медіа за 24 години на акаунт (Stories й окремі елементи каруселі рахуються за своїми правилами). Перевіряти залишок треба через endpoint GET /{ig-user-id}/content_publishing_limit. Автопостери, які «женуть» контент без цієї перевірки, впираються в стіну на 101-му пості.

Сама публікація — теж двокрокова й асинхронна. Спершу POST /{ig-user-id}/media створює container (з image_url/video_url і caption), який повертає creation_id. Потім POST /{ig-user-id}/media_publish з цим creation_id реально викладає пост. Між кроками для відео/Reels контейнер має «дозріти» — статус перевіряють через GET /{creation-id}?fields=status_code, і публікувати треба лише коли FINISHED. Спроба опублікувати IN_PROGRESS-контейнер — часта причина помилок серії 2207xxx.

Вебхуки: підписки й типові граблі

Вебхуки Instagram — це push від Meta на ваш HTTPS-endpoint при подіях: нові коментарі, згадки, повідомлення в директі, story insights. Без них ви змушені поллити API (і швидко з'їдаєте rate limit).

Кроки налаштування, де кожен — потенційна точка відмови:

1. Verify endpoint. Meta шле GET з hub.mode=subscribe, hub.challenge, hub.verify_token. Ваш сервер має звірити verify_token зі своїм і повернути назад рівно hub.challenge зі статусом 200. Найчастіша помилка — повертають JSON замість голого значення challenge.
2. Підписка на поля. Через POST /{app-id}/subscriptions вказуєте object=instagram і fields (наприклад comments,messages,mentions). Забули поле — події просто не приходять, помилки немає.
3. Підписка сторінки/акаунта. Окремо: POST /{ig-user-id}/subscribed_apps з потрібними subscribed_fields. Багато хто робить крок 2 і забуває крок 3 — вебхуки «мовчать».
4. Валідація підпису. Meta підписує кожен payload заголовком X-Hub-Signature-256 (HMAC-SHA256 з вашим app secret). Якщо не перевіряєте — приймаєте будь-який підроблений POST.

Критично: відповідайте на вебхук 200 за < 5 секунд. Уся важка робота (запис у БД, виклики API) — в асинхронну чергу. Якщо тримати з'єднання довше, Meta вважає endpoint нездоровим, робить retry, а після серії невдач відписує вас — і ви тижнями не розумієте, чому події зникли.

Токени: головна причина «раптом усе відвалилось»

Про токени в нас є окремий детальний розбір — Instagram Graph API: токени доступу. Тут — стисло найважливіше з точки зору помилок.

• Short-lived token живе ~1 годину. Годиться тільки щоб одразу обміняти на long-lived.
• Long-lived token живе ~60 днів. Його треба рефрешити (endpoint GET /refresh_access_token з grant_type=ig_refresh_token) до закінчення. Не рефрешнули на 61-й день — інтеграція мертва, юзер має заново проходити OAuth.
• Page access token для Graph API отримується через GET /{user-id}/accounts і залежить від валідності батьківського user token.

Класичний інцидент: усе працювало 2 місяці, потім «раптом» OAuthException code 190. Причина — ніхто не поставив cron на рефреш. Рішення нижче в таблиці.

Таблиця: коди помилок → причина → рішення

Код / тип	Що означає	Причина	Рішення
190 OAuthException	Токен невалідний/протух	Не рефрешнули long-lived, юзер змінив пароль, відкликав доступ	Рефрешити токен до 60 днів; ловити 190 → тригерити повторний OAuth
10 / 200 permissions	Немає потрібного дозволу/scope	Не запросили instagram_manage_insights / _messages під час OAuth	Додати scope, пройти App Review, перезапросити згоду
4 / 17	User/App rate limit hit	Забагато запитів, ігнор X-Business-Use-Case-Usage	Backoff по заголовку usage, кешування, вебхуки замість поллінгу
32	Page-level throttle	Забагато викликів на одну сторінку	Розподілити навантаження, зменшити частоту
100	Invalid parameter	Неправильний field, застаріла версія API, невірний ID	Звірити з докою поточної версії, перевірити ID акаунта
803	Некоректний object ID	Використали IG username замість numeric ID	Резолвити username → id через /ig_hashtag_search або business discovery
368	Тимчасове блокування за abuse	Патерн запитів схожий на зловживання	Пауза, зменшити агресивність, звернутись у підтримку
2207xxx	Content Publishing errors	Формат медіа, URL недоступний, ліміт 100/добу	Перевірити media URL, формат, content_publishing_limit

Практичне правило: будь-яку відповідь API обробляйте як «може бути помилкою». Meta повертає 200 навіть на частину логічних збоїв; помилка — у тілі error.code / error.error_subcode. Логуйте fbtrace_id — це єдине, з чим має сенс іти в Meta Support.

Як обходити ліміти (легально й стабільно)

«Обходити» тут = не впиратись, а не хакати. Робочі техніки:

• Вебхуки замість поллінгу. Найбільший виграш. Замість опитувати «чи є нові коментарі» кожні 30 секунд — отримуйте push. Мінус десятки тисяч зайвих викликів на добу.
• Batch requests. До 50 операцій в одному HTTP-запиті через ?batch=[...]. Один round-trip замість п'ятдесяти.
• Field expansion. Замість N запитів за деталями — один із fields=id,caption,comments{text,username},insights.metric(reach). Тягнете все потрібне за раз.
• Кешування. Метрики постів за минулі періоди не змінюються — кешуйте в БД, не смикайте API повторно. TTL 1-24 год залежно від метрики.
• Читати usage-заголовки й backoff. Про це вище — це різниця між «стабільно» і «ловимо 429 щодня».

Окремо про permissions і App Review — це не про ліміти, але зупиняє інтеграцію намертво. Розширені права (instagram_manage_insights, instagram_manage_messages, instagram_content_publish) у продакшн-режимі вимагають проходження App Review з демо-відео й описом use case. У режимі розробки вони працюють тільки для акаунтів, доданих у ролі застосунку. Класична пастка: усе працює на тестовому акаунті, а в юзерів код 10/200 «permissions error», бо застосунок не пройшов рев'ю. Плануйте App Review заздалегідь — він займає дні.

Best practices, які реально економлять нерви

1. Cron на рефреш токенів (раз на ~50 днів) + алерт, якщо рефреш упав.
2. Idempotency у вебхуках — Meta може прислати одну подію двічі. Дедуплікація по event id.
3. Асинхронна черга (Redis/RabbitMQ) за вебхук-endpoint. HTTP 200 миттєво, обробка окремо.
4. Централізований API-клієнт з вбудованим retry + backoff + логуванням fbtrace_id. Не розкидайте fetch по коду.
5. Моніторинг квоти — дашборд по X-Business-Use-Case-Usage, алерт на 75%.
6. Версіонування — прибийте версію API явно (v23.0), тестуйте перед міграцією на нову.

Як MaxICo Labs це вирішує

Ми будуємо Instagram-інтеграції «під ключ» так, щоб вони не падали через токен чи ліміт:

• Інтеграція Instagram Graph API (аналітика, автопостинг, парсинг метрик) з коректним обробленням лімітів і вебхуків — від $500.
• Бот + CRM (директ-автовідповіді, збір лідів, тегування) на Messaging API — від $1000.
• Платформа/дашборд з багатоакаунтною аналітикою, чергами й моніторингом квоти — від $1500.
• Автоматизація окремих процесів (рефреш токенів, алерти, ETL метрик у вашу БД) — від $300.
• Навчання команди роботі з Graph API, лімітами й вебхуками — від $500.

Для порівняння: збірка кастомної Instagram-платформи «з нуля» на аутсорсі — це $10k+ (ринкові цифри, не наші). Ми закриваємо типові кейси кратно дешевше, бо в нас уже є готові патерни на токени, вебхуки й rate limits. Приклад — наш кейс Instagram Dashboard: багатоакаунтна аналітика з чергами й моніторингом квоти.

Потрібна стабільна інтеграція?

Якщо у вас уже «відвалюється токен» або ви ловите 429 — напишіть Валерію в чат або залиште заявку. Подивимось вашу схему інтеграції, знайдемо, де тече ліміт, і запропонуємо, як зробити щоб працювало без нагляду.