Помилки API — що означає кожен код і як це виправити

FastOG повертає машиночитні коди помилок, коли запит завершується невдачею — підписаний рендер OG-зображення або виклик однієї з адміністративних поверхонь у продукті. Кожна відповідь з помилкою містить:

• error — застарілий короткий токен. Досі присутній у кожній невдачі, щоб старіший клієнт продовжував працювати.
• code — той самий стабільний, задокументований код помилки (таблиця нижче), під назвою, яку використовує публічний API.
• message — опис того, що пішло не так, одним реченням.
• hint — короткий опис простою мовою того, що пішло не так і як це виправити.
• docs_url — посилання на цю сторінку з якорем на розділ для цього коду.
• request_id — зіставляє цю HTTP-невдачу з рядком у таблиці Render Logs на панелі керування (також повертається в заголовку відповіді X-Request-ID). Поверхня, якій нема чого зіставляти, відповідає null, але ключ присутній завжди.

Поверхні в продукті — адмінка Shopify, WooCommerce Studio, міст Wix і демо — відповідають тим самим конвертом для наведених нижче кодів, тож невдача означає те саме, де б ви з нею не зіткнулися. Поверхня модуля може зберігати HTTP-статус, який вона завжди повертала для коду (наприклад, render_failed відповідає 503 на експорті обкладинки та 502 на публічному API); код, повідомлення, підказка й посилання на документацію не змінюються.

Читання відповіді з помилкою

{
  "error": "invalid_signature",
  "code": "invalid_signature",
  "message": "The signature does not match.",
  "hint": "The signature did not match. Re-sign with your HMAC secret after every param change.",
  "request_id": "5f2a9c1e-..."
}

Якщо ви отримали відповідь, яку не розумієте, найшвидший шлях такий:

1. Запишіть code.
2. Перевірте свій конструктор URL — більшість збоїв спричинені помилками підписування, а не проблемами з акаунтом.
3. Зіставте код нижче з точною причиною та виправленням.
4. У панелі керування відкрийте Render Logs і відфільтруйте за тим самим error_code — кожен рядок показує запитані параметри, тож ви можете відтворити (і підтвердити, що request_id збігається).

Підписування та автентифікація

missing_signature

У вашому запиті відсутні параметри запиту key та/або s (підпис).

Виправлення: переконайтеся, що ваш URL містить і key=<api-key>, і s=<hmac-signature>. Скористайтеся SDK або покроковою інструкцією /docs/hmac-signature-guide, щоб його сформувати.

invalid_signature

Значення s не збігається з тим, що генерує ваш HMAC-секрет для цього URL.

Виправлення: підпис охоплює кожен параметр запиту, крім s, із відсортованими ключами. Зміна будь-якого параметра — зокрема зміна порядку, відмінності в URL-кодуванні або додавання пробілів — робить підпис недійсним. Підписуйте заново після кожної зміни. Переконайтеся, що ваш секрет — той самий, що був показаний під час створення API-ключа.

invalid_signature_format

Значення s не є 64-символьним шістнадцятковим рядком.

Виправлення: підпис має бути необробленим SHA-256 у шістнадцятковому форматі (нижній регістр a-f0-9). Якщо ви кодуєте у base64 або обрізаєте результат, використовуйте звичайний шістнадцятковий формат.

expired_timestamp

Надана вами мітка часу t старша за 5 хвилин.

Виправлення: генеруйте мітку часу заново щоразу, коли формуєте URL. Цей код стосується застарілого потоку з підписаним URL; поточний потік HMAC v2 не має мітки часу.

invalid_api_key

Переданий вами key не існує.

Виправлення: скопіюйте повний API-ключ із панелі керування — це публічний ідентифікатор, що починається з sk_. Він публічний і безпечний у URL; саме секрет (ніколи не в URL) доводить володіння.

missing_hmac_secret

Для API-ключа не налаштовано HMAC-секрет.

Виправлення: створіть новий API-ключ у панелі керування — HMAC-секрет генерується й показується один раз під час створення.

Параметр / вхід

invalid_image_url

Властивість із URL (image, brand_logo, logo, avatar, background_image, ...) не є публічним http(s) URL.

Виправлення: передайте публічно доступний для отримання https://... URL. Localhost, приватні IP-адреси та прості шляхи відхиляються, щоб запобігти підробці серверних запитів (SSRF).

Підписка

subscription_required (402)

Запит надійшов до Dynamic API, але ваш обліковий запис не має активного плану. Доступ до API надається лише за підпискою: план є умовою доступу, і він передбачає ту саму градацію покриття й можливостей, яку пропонують застосунки FastOG. Самі рендери не тарифікуються за обсягом — немає ні місячної квоти на рендери, ні оплати за перевищення.

Виправлення: виберіть план Dynamic API у панелі керування та створіть ключ API. Відповідь містить top_up_url, що вказує на сторінку планів.

Сервіс рендерингу

store_blocked (403)

Рендеринг для магазину, пов'язаного з цим ключем, призупинено FastOG (наприклад, через зловживання або надмірне використання). Зображення, уже кешовані на периферії, можуть і далі віддаватися, доки не спливе їхній термін дії. Зверніться до підтримки, щоб вирішити це питання; жодні зміни в запиті не допоможуть.

render_unreachable

Не вдалося зв'язатися із сервісом рендерингу (коротке вікно перезапуску).

Виправлення: повторіть спробу за кілька секунд. Цю спробу рендерингу не зараховано.

render_failed

Сервіс рендерингу повернув помилку на ваш запит.

Виправлення: перевірте властивості шаблону — задовгі/некоректні значення, непідтримувані поля або недоступне зовнішнє зображення. Відповідь містить відповідний status. Рендеринг не зараховано.

Поверхні адміністратора магазину

Ці коди відповідають з адміністративної панелі Shopify та WooCommerce Studio — вбудованих редакторів, у яких працює продавець, а не з підписаного API. Кілька з них спільні з публічним API (invalid_image_url, render_failed, invalid_signature); для них зберігається запис, задокументований вище.

Міст Wix

Міст Wix підписується застосунком Wix, а не сесією продавця, тому його помилки адресовані розробнику застосунку. Кожна відповідь усе одно містить code і request_id; ідентифікатор запиту мосту — це той, що з підписаного конверта.

Демонстраційна поверхня

Демо — це консоль продажів, доступна лише власнику, а не кінцева точка для продавців.

Коди редакторів scoped-правил

Редактори scoped-правил (адмінка Shopify і WooCommerce Studio) самі перекладають ці токени мовою продавця, тому їхні відповіді містять error і code, але не містять hint — другий англомовний опис лише розійшовся б із локалізованим, який продавець насправді бачить:

scope_already_defined, scoped_rule_limit_reached, scoped_rules_not_on_plan, scope_value_required, scope_value_too_long, unknown_scope_type, base_rule_required, scoped_rules_product_only, cannot_delete_base_rule.

Усе ще не працює?

• Відкрийте сторінку Render Logs у панелі керування — кожен результат (успіх і відхилення) наведено з його error_code, статусом HTTP і запитаними параметрами.
• Запустіть php artisan og:diagnose на підписаному URL, щоб пройти весь конвеєр і побачити, на якому етапі виникає збій.
• Перегляньте документацію в бічній панелі для фреймворку, який ви використовуєте (Next.js, Express, SvelteKit, ...).