Коды ошибок и ограничения

Что вернёт API, когда баллов не хватает, карта не найдена или ключ отозван. Разбирайте код, а не текст сообщения.

Ошибка API — это всегда JSON одного вида: машинный код и человеческий текст. Разбирайте code: текст сообщения может измениться, код — нет.

Любая ошибка

{
  "error": {
    "code": "INSUFFICIENT_POINTS",
    "message": "Недостаточно баллов на карте",
    "details": { "balance": 40, "requested": 100 }
  }
}

Общие

Код	HTTP	Что случилось
`VALIDATION_ERROR`	400	Тело запроса не прошло проверку. В details — какое поле
`UNAUTHORIZED`	401	Ключ не передан, недействителен или отозван
`FORBIDDEN`	403	У ключа нет нужной области доступа
`NOT_FOUND`	404	Объекта нет — или он принадлежит другой компании. Сюда же попадает чек с чужой или выдуманной точкой продаж: на ней держатся и правила, и выручка в отчётах
`CONFLICT`	409	Состояние изменилось: например, гость с таким телефоном уже есть
`RATE_LIMITED`	429	Слишком много запросов; повторите позже
`CAPTCHA_REQUIRED`	403	Нужна проверка «не робот»: с третьего кода подряд на один адрес

Лояльность

Код	HTTP	Что случилось
`CARD_NOT_FOUND`	404	Карты с таким штрихкодом или телефоном нет
`CARD_BLOCKED`	409	Карта заблокирована — операции по ней запрещены
`INSUFFICIENT_POINTS`	409	На карте меньше баллов, чем просят списать
`REDEEM_LIMIT_EXCEEDED`	409	Списание больше потолка: правило ограничивает долю чека — в том числе правило, действующее только на этой точке
`PROGRAM_INACTIVE`	409	Программа выключена — чеки по ней не проводятся
`CARDS_LIMIT_REACHED`	409	Исчерпан лимит карт по тарифу
`CODE_QUOTA_EXCEEDED`	429	Исчерпана месячная квота подтверждений номера
`TRANSACTION_ALREADY_REFUNDED`	409	Этот чек уже возвращён
`IDEMPOTENCY_KEY_REUSED`	422	Тот же Idempotency-Key прислан с другим телом запроса

Карты в кошельке

Код	HTTP	Что случилось
`PASS_NOT_FOUND`	404	Пропуск не найден: карта удалена или идентификатор чужой
`PASS_GENERATION_FAILED`	500	Не удалось собрать файл карты — пишите в поддержку

Инфраструктура

Код	HTTP	Что случилось
`INTERNAL_ERROR`	500	Ошибка на нашей стороне. Повторить можно, но не сразу
`SERVICE_UNAVAILABLE`	503	Сервис временно недоступен: обслуживание или сбой

Ограничения по частоте

Запросы с одного ключа ограничены по частоте, отдельно — выдача кодов подтверждения на номер и на адрес. Ограничители защищают не нас, а вас: перебор с чужого адреса тратит вашу квоту подтверждений, а она оплачена.

RATE_LIMITED — сбавьте темп и повторите; разумная стратегия — удвоение задержки.
CODE_QUOTA_EXCEEDED — исчерпана месячная квота подтверждений тарифа. Выдача карт продолжается бесплатными каналами.
Ограничение по частоте не применяется к возвратам и чтению карт: касса не должна останавливаться из-за очереди.

Что смотреть при разборе

Журнал действий в кабинете — что менялось и кто это сделал.
История доставок на вкладке «Вебхуки» — код ответа вашего сервера по каждой попытке.
История карты — GET /cards/:id/history: полное движение баллов, включая сгорание и ручные правки.
status.snovacard.ru — состояние сервисов, если ошибки пошли разом и у всех.

Частые вопросы

Чем отличается 404 «карты нет» от 404 «чужая компания»?

Ничем, и это намеренно: ответ «объект есть, но не ваш» сообщал бы посторонним факт существования карты. Изоляция компаний проверяется на уровне базы, а не кода, поэтому чужая строка просто не видна.

Стоит ли разбирать текст сообщения?

Нет. Текст пишется для человека и может измениться в любой момент — например, стать понятнее. Машинный контракт — это поле code.

Как отличить временную ошибку от постоянной?

По HTTP-статусу: 5xx — наша сторона, повтор оправдан; 4xx — запрос нужно исправить, повтор ничего не изменит. Исключение — 429: он временный, но требует паузы, а не немедленного повтора.

Первые 50 карт — бесплатно. Программа настраивается за вечер.

Создать программу