# Расходы и лимиты

Карта бесплатна; сервисные запросы используют квоту, затем оплачиваются с баланса.

## Тарифы

| Услуга | Бесплатно в месяц | За 1 000 сверх квоты |
| --- | --- | --- |
| Карта и SDK | Без ограничений по квоте API | Бесплатно |
| Подсказки адресов | 5 000 | 15 ₽ |
| Геокодинг | 3 000 | 49 ₽ |
| Обратный геокодинг | 3 000 | 49 ₽ |
| Маршрут | 1 000 | 99 ₽ |
| Элемент матрицы расстояний | 2 000 | 39 ₽ |
| resolve, status | В пределах частоты запросов ключа | Без отдельной оплаты |

Квота общая для проектов аккаунта. Матрица учитывается по парам точек, остальные платные операции — по выполненным запросам. Применимый тариф и доступные операции проверяйте в кабинете.



## Бесплатная проба API

[Создайте аккаунт](https://mmapps.ru/app/register), подтвердите email и выпустите ключ в разделе [«Проекты и ключи»](https://mmapps.ru/app/projects). Запросы в пределах бесплатной квоты доступны без пополнения баланса и привязки банковской карты. [Первый запрос по шагам](https://mmapps.ru/docs/getting-started).

Когда квота закончится, новые платные запросы потребуют предоплаты и доступного бюджета. Годовой лицензии и обязательной подписки нет.

## Хранение результатов

Результаты API можно сохранять у себя: в базе данных, кеше, заказах и отчётах. Используйте найденные адреса, координаты и рассчитанные маршруты повторно, в том числе на другой карте. Чтение сохранённого результата не вызывает новый запрос к Ммаппс и не расходует квоту.

Соблюдайте лицензии исходных данных, включая OpenStreetMap, и требования к персональным данным. Право сохранять результаты закреплено в [пункте 2.3 пользовательского соглашения](https://mmapps.ru/documents/terms#sdk).

Для поиска адресов и геокодирования атрибуцию OpenStreetMap можно разместить один раз в общем футере приложения, без подписи под каждым полем адреса. [Правила размещения и пример](https://mmapps.ru/docs/addresses#atribuciia-openstreetmap).

## Что считается операцией

- Поиск, геокодинг и обратный геокодинг учитываются при успешном выполнении, в том числе с пустым результатом или необходимостью уточнения.
- Расчёт маршрута — одна операция `route`.
- Матрица — `N × M` элементов, включая повторяющиеся пары, диагональ и завершённые `no_route`.
- В маршруте и матрице по адресам каждый выполненный поиск текста — отдельный `geocode`. До подтверждения адресов сам маршрут или матрица не оплачивается.
- `resolve` и `status` — без отдельной платы, в пределах частоты запросов ключа.
- Перемещение карты, маркеры, кластеры, отображение готовой геометрии и воспроизведение Ваших данных на таймлайне не расходуют квоту API.

Ошибка запроса или сервиса отличается от успешного ответа «ничего не найдено». У маршрута проверяйте `outcome`, у матрицы — статус каждой пары. При частичном выполнении поиска по адресам уже выполненные операции могут быть учтены; смотрите квитанцию и историю использования.

## Баланс и месячный бюджет

После исчерпания бесплатной квоты нужны доступный баланс и разрешённый бюджет. Бюджет `0` оставляет только бесплатную квоту. Бюджеты аккаунта и проекта действуют одновременно. Создание другого проекта не увеличивает квоту.

Месяц учитывается по Москве. [«Лимиты и уведомления»](https://mmapps.ru/app/limits) позволяют ограничить расходы, [«Использование»](https://mmapps.ru/app/usage) — посмотреть историю, применить фильтры и выгрузить CSV. В статистике матрицы запросы и элементы указаны отдельно.

## Повтор запроса

Для новой логической операции создавайте новый `Idempotency-Key`; в SDK это `operationKey`. При сетевом сбое повторяйте то же тело с прежним ключом. Не создавайте новый ключ при каждом автоматическом повторе.

Изменение тела при прежнем ключе возвращает 409. Сервис хранит ответ для повторной выдачи 15 минут; после этого повтор не запускает новую оплачиваемую операцию. Этот срок не ограничивает хранение полученного результата в Вашей базе по условиям соглашения. Если ответ для повтора истёк или операция ещё обрабатывается, сначала уточните её состояние.

Заголовок `X-Usage-Operation` содержит идентификатор операции. Квитанцию можно прочитать через `GET /platform/v1/usage-operations/{id}` тем же API-ключом с нужными правами. `X-Charged-Microrub` передаёт сумму целым числом в миллионных долях рубля; `X-Geo-Funding` — `free`, `paid` или `mixed`. Для обычной матрицы `X-Geo-Quantity`, `X-Geo-Free-Units` и `X-Geo-Paid-Units` показывают число элементов.

## Ошибки

| HTTP | Что делать |
| --- | --- |
| 401 | Проверить API-ключ и его отзыв |
| 402 | Проверить доступный баланс |
| 403 | Проверить права, разрешённый сайт или IP, бюджет и состояние аккаунта |
| 409 | Проверить повтор операции, её состояние или актуальность `ref` |
| 413 | Уменьшить размер запроса |
| 422 | Исправить поля по схеме запроса |
| 429 | Снизить частоту, учитывать `Retry-After`, если он есть |
| 503 | Показать временную недоступность; при разрешённом повторе сохранить ключ операции |

По умолчанию JSON ошибки содержит `error.code`, `error.message`, `error.request_id`, `error.retryable`. Для `Accept: application/problem+json` используется формат Problem Details из OpenAPI. Решение о повторе принимайте по коду и `retryable`, а не только по HTTP-статусу.

`ROUTING_UNAVAILABLE` означает недоступность расчёта. `INCOMPATIBLE_GEO_SCHEMA` — временную несовместимость сервиса; не пытайтесь обходить её запросом старого формата. При `IDEMPOTENCY_SCHEMA_CHANGED` прежняя операция уже учтена: новый ключ может создать новый расход.

## Пополнения и возвраты

Пополняйте баланс через кабинет, минимум — 300 ₽. Возврат со страницы оплаты ещё не подтверждает зачисление — дождитесь подтверждённого статуса платежа. После регистрации чека в разделе [«Платежи»](https://mmapps.ru/app/payments) появится кнопка «Скачать чек»: электронную копию можно открыть в браузере и распечатать или сохранить в PDF. Правила возвратов описаны в [пользовательском соглашении](https://mmapps.ru/documents/terms#payments).

Для обращения в поддержку достаточно кода ошибки и ID запроса. Не отправляйте ключи и географические данные пользователей.