ApiScoring APIГайды
Ошибки
Коды ответов, обёртка problem+json и KA-сообщения
Ошибки
Все неуспешные ответы проходят через точку публикации и приходят в обёртке
RFC 9457 problem+json; исходное сообщение KA-протокола ({"message": "..."}) едет в поле detail дословно.
Формат
{
"type": "about:blank",
"title": "Unauthorized",
"status": 401,
"detail": "{\"message\":\"unknown X-KA-Access-Key\"}",
"instance": "/api/v1/scoring"
}| Поле | Описание |
|---|---|
title | HTTP-причина (короткая фраза статуса) |
status | HTTP-код (дублирует код ответа) |
detail | строка, внутри которой JSON с полем message — KA-текст |
instance | путь точки публикации |
detail — это JSON-строка, а не вложенный объект. Распарсите её
вторым шагом, если нужно поле message. Матчитесь на status, а не
на тексты: формулировки message могут меняться между релизами.
Коды и действия
| Код | Причина | Действие интегратора |
|---|---|---|
400 | тело не JSON или поле не прошло валидацию (например сумма числом) | исправить запрос; текст — в detail.message |
401 | заголовок X-KA-Access-Key не передан или неизвестен | проверить конфигурацию ключа |
403 | ключ валиден, но endpoint вне выданного scope | работать только с выданными ручками или запросить расширение |
500 | внутренняя ошибка платформы | retry с экспоненциальным backoff (2-3 попытки); если повторяется — владельцу с orderRef/временем |
Сообщения KA-уровня (внутри detail)
| Сообщение | Где возникает | Смысл |
|---|---|---|
X-KA-Access-Key header is required | все ручки | заголовок не передан |
unknown X-KA-Access-Key | все ручки | ключ не существует |
X-KA-Access-Key is not provisioned for this endpoint (scope …) | все ручки | ключ вне scope |
malformed JSON body | score/verdict | тело не разобралось (в т.ч. сумма числом) |
paymentIdKey was not registered by create | payment-руки | финал без create (вне scoring scope) |
Не все 400 возвращают конкретное поле в message: некоторые
валидации сообщают только сам факт. Сверяйте запрос со схемами
openapi.yaml — это быстрее подбора.