Ошибки

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

Бизнес-ошибки публичного Merchant API возвращаются в стабильном конверте:

{
  "error": {
    "code": "invalid_api_key",
    "message": "invalid api key"
  }
}

• code — стабильный машиночитаемый код (ориентируйтесь на него).
• message — краткое нелокализованное описание для логов.

Для 401 дополнительно возвращается заголовок WWW-Authenticate: Bearer.

Общие коды

HTTP	code	Значение	Что делать
400	idempotency_key_required	Отсутствует заголовок Idempotency-Key.	Добавьте заголовок.
400	idempotency_key_invalid	Ключ недопустимой формы/длины.	Исправьте ключ (печатаемый ASCII, 1–255).
401	invalid_api_key	Неверный/неизвестный/отозванный ключ.	Проверьте ключ; при компрометации — отзыв и новый ключ.
403	forbidden	У ключа нет нужной возможности.	Выдайте ключу нужную возможность (Аутентификация).
404	payment_not_found	Платёж не найден (/v1/payments).	Проверьте reference. Неизвестная/некорректная/чужая ссылка неразличимы.
404	invoice_not_found	Счёт не найден (/v1/cashier/invoices).	То же.
409	idempotency_conflict	Тот же Idempotency-Key для другого запроса.	Не переиспользуйте ключ для другой команды.
422	payment_amount_invalid	Сумма недопустима.	Исправьте amount (строка, два знака).
429	rate_limited	Слишком много запросов.	Подождите Retry-After секунд.
500	internal_error	Внутренняя ошибка.	Повторите позже с тем же ключом; при повторении — в поддержку.
503	service_unavailable	Сервис временно недоступен.	Повторите позже с тем же ключом.

Коды счетов Cashier (cashier_*, ambiguous_create_blocked, customer_phone_invalid, amount_not_whole_tenge, payer_rate_limited и др.) собраны в таблице Создание счёта.

Ошибки формы запроса (валидация)

Если тело запроса имеет неверную форму (неправильный тип поля, лишнее поле, несоответствие шаблону amount, merchant_order_id или customer_phone), возвращается 422 в стандартном формате FastAPI:

{
  "detail": [
    { "type": "string_pattern_mismatch", "loc": ["body", "amount"], "msg": "..." }
  ]
}

Входные значения из ошибки удаляются (не эхом). Отличайте этот detail-формат от конверта {"error": {...}} бизнес-ошибок выше.

Повторы

• GET безопасно повторять при сетевых ошибках, 429 и 5xx.
• POST повторяйте только с тем же Idempotency-Key и тем же телом (см. Идемпотентность). Нет ответа — не значит «не создано».

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

Лимиты применяются (429 rate_limited с Retry-After; для счетов Cashier также payer_rate_limited), но числовые значения не опубликованы и могут меняться. Задавайте клиентские таймауты и идемпотентные повторы с экспоненциальной паузой.