Ошибки API

Общие положения

Merchant API возвращает ошибки в едином формате.

Продавец должен обрабатывать ошибки спокойно: показать понятное сообщение пользователю, сохранить trace_id в своих логах и не раскрывать secret API key.

trace_id нужен для диагностики. Если обращаетесь в поддержку, укажите trace_id, время запроса и endpoint.

Формат ошибки

Ошибка содержит основные поля:

• success;
• message;
• error.code;
• error.details;
• trace_id.

success будет false.

message содержит короткое описание ошибки.

error.code содержит стабильный код ошибки.

error.details может содержать дополнительные детали, например ошибки проверки полей.

trace_id помогает найти конкретный запрос при разборе проблемы.

Что логировать

На стороне продавца полезно логировать:

• endpoint;
• HTTP method;
• HTTP status;
• error.code;
• message;
• trace_id;
• свой order_id, если он есть.

Нельзя логировать полный secret API key.

Ошибки авторизации

API_KEY_REQUIRED

Код API_KEY_REQUIRED означает, что API не получил Bearer token.

Проверьте header:

Authorization: Bearer weelay_secret_...

API_KEY_INVALID_FORMAT

Код API_KEY_INVALID_FORMAT означает, что ключ имеет неверный формат.

Secret key должен начинаться с weelay_secret_.

API_KEY_INVALID

Код API_KEY_INVALID означает, что ключ не найден или неверен.

Проверьте, что используете актуальный secret API key из dashboard проекта.

API_KEY_REVOKED

Код API_KEY_REVOKED означает, что ключ был отозван.

Создайте новый secret API key в dashboard проекта и обновите backend-настройки.

PROJECT_NOT_ACTIVE

Код PROJECT_NOT_ACTIVE означает, что проект неактивен.

Проверьте статус проекта в dashboard.

ACCOUNT_NOT_ACTIVE

Код ACCOUNT_NOT_ACTIVE означает, что аккаунт неактивен.

Проверьте статус аккаунта или обратитесь в поддержку.

Ошибки проверки данных

VALIDATION_ERROR

Код VALIDATION_ERROR означает, что данные запроса не прошли проверку.

Чаще всего это связано с неправильным amount, слишком длинным order_id, неверным status, limit или page.

Проверьте error.details.

Для создания счёта amount должен быть положительной строкой максимум с 2 знаками после точки.

Ошибки доступа и поиска

FORBIDDEN

Код FORBIDDEN означает, что действие запрещено.

Проверьте, что запрос выполняется с правильным ключом и для правильного проекта.

NOT_FOUND

Код NOT_FOUND означает, что ресурс не найден.

Например, счёт с указанным id не существует или не относится к текущему проекту.

Проверьте invoice id и secret API key проекта.

METHOD_NOT_ALLOWED

Код METHOD_NOT_ALLOWED означает, что endpoint не поддерживает выбранный HTTP method.

Проверьте, что используете правильный method: GET или POST.

Лимиты запросов

RATE_LIMITED

Код RATE_LIMITED означает, что отправлено слишком много запросов.

HTTP status обычно 429.

В этом случае backend продавца должен подождать и повторить запрос позже, если повтор допустим для сценария.

Не нужно бесконечно повторять запрос без задержки.

Внутренняя ошибка

INTERNAL_SERVER_ERROR

Код INTERNAL_SERVER_ERROR означает, что произошла внутренняя ошибка сервера.

Продавец должен сохранить trace_id и повторить запрос позже, если это безопасно.

Если ошибка повторяется, обратитесь в поддержку и укажите trace_id.

Ошибки создания счёта

При создании счёта возможны ошибки:

• неверный amount;
• отсутствующий amount;
• слишком длинный order_id;
• превышение лимита;
• неактивный проект;
• неверный API key.

Если создание счёта не удалось, не показывайте покупателю старый или случайный payment_url.

Сначала получите успешный ответ от Weelay.

Ошибки получения счёта

При получении счёта возможны ошибки:

• счёт не найден;
• счёт принадлежит другому проекту;
• неверный secret API key;
• превышен лимит запросов.

Проверьте invoice id, проект и API key.

Как показывать ошибку покупателю

Покупателю не нужно показывать технический код ошибки API.

Лучше показать простое сообщение:

Не удалось создать страницу оплаты. Попробуйте позже или обратитесь к продавцу.

Технические детали должны остаться в логах продавца.

Как обрабатывать ошибку в backend

Рекомендуемый порядок:

1. Получить HTTP status.
2. Прочитать error.code.
3. Сохранить trace_id.
4. Сохранить свой order_id, если он есть.
5. Не логировать secret API key.
6. Решить, можно ли безопасно повторить запрос.
7. Показать покупателю понятное сообщение.

Когда можно повторять запрос

Запрос можно повторить позже, если ошибка временная, например RATE_LIMITED или INTERNAL_SERVER_ERROR.

При повторе создания счёта используйте тот же Idempotency-Key, если это та же операция создания счёта.

Если ошибка VALIDATION_ERROR, сначала исправьте данные запроса.

Если ошибка авторизации, сначала исправьте API key или статус проекта.

Production-чеклист

Перед запуском проверьте:

• backend сохраняет trace_id;
• ошибки не раскрывают secret API key;
• покупатель видит понятное сообщение;
• VALIDATION_ERROR обрабатывается отдельно;
• RATE_LIMITED не вызывает бесконечный повтор без задержки;
• повтор создания счёта использует тот же Idempotency-Key;
• support может найти заказ по order_id и trace_id.

Итог

Ошибки API нужно обрабатывать предсказуемо.

Главные поля для продавца: error.code, error.details и trace_id.

Главное правило безопасности: не логировать и не показывать полный secret API key.