# Справочник ошибок API Minimax

## Таблица кодов ошибок

| Код | Название | Причина | Решение |
| --- | --- | --- | --- |
| `0` | Успех | Запрос выполнен | Ничего делать не нужно |
| `1002` | Ограничена частота | Слишком много запросов в минуту | Подождите 10–30 секунд и повторите с экспоненциальной задержкой |
| `1004` | Ошибка авторизации | Ключ API неверен, истёк или отсутствует | Проверьте ключ на platform.minimax.io, отсутствие пробелов; при истечении создайте новый |
| `1008` | Недостаточный баланс | На аккаунте закончились кредиты | Пополните баланс на platform.minimax.io > Billing |
| `1026` | Содержимое отклонено | Текст или промпт не прошёл модерацию | Уберите чувствительные, жестокие или откровенные фрагменты |
| `2013` | Неверные параметры | Неподходящие типы или значения вне допустимого диапазона | Сверьте все параметры со схемой API |
| `2049` | Неверный формат ключа API | Строка ключа повреждена | Проверьте завершающие переводы строк, лишние пробелы и ошибки копирования |

## Дерево диагностики

```
Получили ответ с ошибкой?
│
├─ Проверьте base_resp.status_code
│
├─ 1002 (ограничена частота)
│  ├─ Отправляете много запросов? → Добавьте задержку между вызовами.
│  ├─ Запрос всего один? → RPM вашего тарифа может быть низким (Starter = 10 RPM).
│  └─ Действие: подождите и повторите с экспоненциальной задержкой (10, 20, 40 секунд).
│
├─ 1004 (ошибка авторизации)
│  ├─ Ключ API задан? → Проверьте формат заголовка Authorization.
│  ├─ Это ключ Coding Plan? → Для музыки нужен ключ Pay-as-you-go.
│  ├─ Срок действия ключа истёк? → Создайте новый на platform.minimax.io.
│  └─ Действие: проверьте формат «Authorization: Bearer <key>» без лишних пробелов.
│
├─ 1008 (недостаточный баланс)
│  ├─ Проверьте остаток кредитов на platform.minimax.io.
│  └─ Действие: пополните баланс или перейдите на более высокий тариф.
│
├─ 1026 (содержимое отклонено)
│  ├─ Проверьте текст песни на чувствительные слова и темы.
│  ├─ Проверьте промпт на откровенное содержимое.
│  └─ Действие: исправьте и отправьте повторно; правила модерации не опубликованы.
│
├─ 2013 (неверные параметры)
│  ├─ model = "music-2.5", а не "music-01" или другое значение?
│  ├─ Длина lyrics — от 1 до 3500 символов?
│  ├─ Длина prompt — не больше 2000 символов?
│  ├─ sample_rate: 16000, 24000, 32000 или 44100?
│  ├─ bitrate: 32000, 64000, 128000 или 256000?
│  ├─ format: "mp3", "wav" или "pcm"?
│  ├─ output_format: "hex" или "url"?
│  └─ Действие: исправьте неверный параметр и повторите запрос.
│
├─ 2049 (неверный формат ключа API)
│  ├─ В конце ключа есть перевод строки или пробелы?
│  ├─ Он правильно скопирован из панели управления?
│  └─ Действие: скопируйте ключ заново и уберите пробелы.
│
└─ data.status === 1 (это не ошибка!)
   └─ Генерация ещё идёт. Проверьте статус позже или дождитесь окончания.
```

## Частые ошибки параметров

| Ошибка | Проблема | Исправление |
| --- | --- | --- |
| `"model": "music-01"` | Не та модель для собственного API | Используйте `"music-2.5"` |
| `"lyrics": ""` | Пустой текст песни | Нужен текст длиной 1–3500 символов |
| `"sample_rate": 48000` | Недопустимая частота дискретизации | Используйте 16000, 24000, 32000 или 44100 |
| `"bitrate": 320000` | Недопустимый битрейт | Используйте 32000, 64000, 128000 или 256000 |
| `"format": "flac"` | Неподдерживаемый формат | Используйте "mp3", "wav" или "pcm" |
| `"stream": true` + `"output_format": "url"` | Поток работает только с hex | Задайте `output_format: "hex"` или отключите поток |
| Отсутствует заголовок `Content-Type` | Сервер не может разобрать JSON | Добавьте `Content-Type: application/json` |
| В конце ключа есть `\n` | Авторизация не срабатывает | Уберите завершающий перевод строки |
| Промпт длиннее 2000 символов | API отклоняет запрос | Сократите промпт |
| Текст длиннее 3500 символов | API отклоняет запрос | Сократите текст или уберите часть тегов структуры |

## Коды HTTP

| Статус HTTP | Значение | Действие |
| --- | --- | --- |
| `200` | Запрос обработан | Проверьте `base_resp.status_code` на ошибки уровня API |
| `401` | Нет авторизации | Ключ API отсутствует или неверен |
| `429` | Слишком много запросов | Уменьшите частоту и повторите позже |
| `500` | Ошибка сервера | Повторите через небольшое время |
| `503` | Сервис недоступен | Серверы Minimax перегружены; повторите позже |