Ошибки 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-символьной hex-строкой.

Исправление: подпись должна быть в виде сырого SHA-256 hex (нижний регистр a-f0-9). Если вы кодируете в base64 или обрезаете вывод, используйте обычный hex.

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.

Исправление: передайте публично доступный по сети URL https://.... Localhost, частные IP-адреса и пути без хоста отклоняются для предотвращения подделки запросов на стороне сервера.

Подписка

subscription_required (402)

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

Решение: выберите тариф Dynamic API в панели управления и создайте ключ API. В ответе будет top_up_url со ссылкой на страницу тарифов.

Сервис рендеринга

store_blocked (403)

Рендеринг для магазина, которому принадлежит этот ключ, приостановлен FastOG (например, из-за злоупотребления или неконтролируемого использования). Уже закэшированные на периферии изображения могут продолжать отдаваться до истечения их срока действия. Обратитесь в поддержку, чтобы решить вопрос; никакие изменения в запросе это не исправят.

render_unreachable

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

Исправление: повторите попытку через несколько секунд. Рендер не был засчитан для этой попытки.

render_failed

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

Исправление: проверьте свойства шаблона (props) — слишком длинные или некорректные значения, неподдерживаемые поля или недоступное вышестоящее изображение. Ответ содержит исходную ошибку status. Рендер не был засчитан.

Интерфейсы администратора магазина

Эти коды отвечают из административной панели Shopify и WooCommerce Studio — встроенных редакторов, в которых работает продавец, а не из подписанного API. Несколько из них используются совместно с публичным API (invalid_image_url, render_failed, invalid_signature); для них сохраняется описание, приведённое выше.

Мост Wix

Мост Wix подписывается приложением Wix, а не сессией мерчанта, поэтому его ошибки адресованы разработчику приложения. Каждый ответ по-прежнему содержит code и request_id; идентификатор запроса моста — это идентификатор из подписанного конверта.

Демонстрационная поверхность

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

Коды редакторов правил с областью действия

Редакторы правил с областью действия (админка 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, ...).