Формат ошибок
Как выглядит отказ API, как его разбирать и какие отказы возможны сегодня.
Отказ, который вернуло приложение, всегда одной формы, на любой ручке и при любом статусе HTTP.
{
"error": {
"code": "unknown_filter",
"message": "Unknown parameters: verbose",
"details": {
"unknown": [
"verbose"
],
"allowed": []
}
}
}| Поле | Вид | В ответе | Что это |
|---|---|---|---|
error | объект | всегда | Сам отказ. В успешном ответе этого поля нет никогда. |
error.code | строкаunauthorized cookie_auth_not_allowed forbidden unknown_filter bad_body too_large not_found too_many_requests not_implemented internal validation_failed bad_amount conflict identifier_invalid keyring_unavailable dependency_unavailable | всегда | Код отказа. По нему клиент выбирает, что делать. Общие коды перечислены в каталоге ниже, коды отдельной ручки в справочнике под ней. |
error.message | строка | всегда | Объяснение для человека, по-английски. Текст может меняться, разбирать его кодом нельзя. |
error.details | любое значение | не всегда | Подробности, если они есть. Состав зависит от кода; часто здесь лежит rule, у отказа проверки ещё field. |
Как разбирать отказ
- Статус HTTP говорит, чья это ошибка. Статус 4xx: запрос надо исправить, повтор без правки даст тот же ответ. Исключения повторяют тем же запросом позже: 429, 409 с правилом
request_in_progressилиrefund_in_progress, 409 без правила иkeyring_unavailableу создания платежа. Статус 5xx: сбой на нашей стороне. error.codeговорит, что именно не так.error.details.rule, если он есть, называет точную причину. Отказы входа различаются именно им.
Незнакомый код обрабатывайте по статусу HTTP: новые коды и правила могут появляться, о них пишет журнал изменений.
Текст error.message написан для человека по-английски и может меняться. Не разбирайте его кодом: ветвитесь по error.code и error.details.rule. Что значит каждый отказ, по-русски сказано в каталоге ниже и в справочнике.
Если приложение недоступно целиком, ответ 502 или 504 отдаёт прокси перед ним, и тела в этой форме у такого ответа нет. Не разбирайте его как JSON, обращайтесь с ним как с любым 5xx.
Номер запроса
У каждого ответа, успешного или нет, есть заголовок X-Request-Id. Сохраняйте его вместе с отказом в своём журнале и называйте поддержке: по нему запрос находят сразу.
Каталог отказов
Здесь отказы, общие для всех ручек; свои отказы ручки описаны в справочнике под ней. Под каждой строкой раскрывается пример ответа.
Вход
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 401 | unauthorized | Заголовка Проверить, что заголовок передан и ключ скопирован целиком, без пробелов и переводов строки. |
Пример ответа | ||
| 401 | unauthorizedapi_key_revoked | Ключ верный, но отозван или заменён перегенерацией. Отзыв окончателен. Получить у администратора новый ключ. |
Пример ответа | ||
| 401 | unauthorizedapi_key_expired | Ключ верный, но его срок истёк. Получить у администратора новый ключ. |
Пример ответа | ||
| 401 | unauthorizedapi_key_disabled | Ключ верный, но выключен администратором. Выключенный ключ можно включить обратно. Попросить администратора включить ключ. |
Пример ответа | ||
| 401 | cookie_auth_not_allowed | Вместе с запросом пришла кука сессии консоли оператора. Так бывает, когда запрос скопирован из панели браузера. Убрать куку и передать ключ API заголовком |
Пример ответа | ||
| 403 | forbiddenmerchant_not_active | Ключ верный, но мерчант не в работе: ещё не активирован, выключен или в архиве. Уточнить у администратора статус мерчанта. |
Пример ответа | ||
| 403 | forbiddenenvironment_closed | Ключ верный, мерчант в работе, но контур этого ключа мерчанту закрыт. Работать ключом другого контура либо попросить администратора открыть контур. |
Пример ответа | ||
Запрос
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 400 | unknown_filter | В адресе есть параметр, которого у ручки нет. Незнакомый параметр не пропускается молча: Убрать параметр или исправить его имя. |
Пример ответа | ||
| 400 | bad_body | Тело запроса не разобралось как JSON. Исправить тело запроса. |
Пример ответа | ||
| 413 | too_large | Тело запроса больше допустимого размера. Уменьшить тело запроса. |
Пример ответа | ||
| 404 | not_found | Такого адреса нет: опечатка в пути или не тот метод HTTP. Сверить адрес и метод со справочником. |
Пример ответа | ||
Предел частоты
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 429 | too_many_requests | Превышен предел частоты запросов с одного адреса. Повторить позже: заголовок |
Пример ответа | ||
Наша сторона
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 500 | internal | Сбой на нашей стороне. Причина наружу не выдаётся, в Повторить тот же запрос позже, создание платежа и возврата с тем же ключом повтора. Если повторяется, сообщить поддержке номер запроса. |
Пример ответа | ||