Ошибки и rate limits
HTTP-коды, которые возвращает Memo AI API (401, 403, 422, 429, 5xx), формат JSON-ошибки, причины каждого и как обрабатывать rate limits.
API использует стандартные HTTP-коды. 2xx — успех; 4xx — что-то в запросе нужно исправить.
Коды статусов
| Статус | Значение | Типичная причина |
|---|---|---|
200 | OK | Запрос успешен. |
201 | Created | Ключ создан (управление). |
204 | No Content | Ключ отозван (управление). |
401 | Unauthorized | Нет/неверный/истёкший ключ или ключ передан в URL. |
402 | Payment Required | Закончились минуты тарифа (загрузки). |
403 | Forbidden | План без доступа к API (api_access_denied) или ключ без права загрузки (upload_scope_required). |
404 | Not Found | Ресурс не существует в вашем workspace. |
408 | Request Timeout | Загрузка зависла или шла слишком долго. |
409 | Conflict | Тот же Idempotency-Key еще в полете. |
411 | Length Required | Загрузка без Content-Length. |
413 | Payload Too Large | Файл больше лимита загрузки 2 ГБ. |
422 | Unprocessable Entity | Неверный параметр (например, плохой format, слишком много ids). |
429 | Too Many Requests | Превышен rate limit или лимит загрузок. |
5xx | Ошибка сервера | Временная — повторите с backoff. |
Формат ошибки
Большинство ошибок возвращают JSON с полем detail. Ошибки доступа/плана включают машиночитаемый
code:
{
"detail": {
"code": "api_access_denied",
"message": "Your current plan does not include API access. Please upgrade to a plan with API & MCP support."
}
}{
"detail": "Invalid API key"
}Частые случаи
| Что видите | Почему | Как исправить |
|---|---|---|
401 на каждом вызове | Ключ отозван, истёк или с пробелом в конце | Создайте новый ключ, аккуратно скопируйте |
401 с ключом в query-строке | Ключи в URL отклоняются намеренно | Перенесите ключ в заголовок Authorization |
403 api_access_denied | План без API & MCP | Перейдите на Pro или Expert |
404 на известном ID | Расшифровка в другом workspace | Используйте ключ того workspace |
422 на экспорте | format не md/txt или ids пуст/больше 100 | Исправьте параметр |
Ошибки загрузки и удаления
Загрузка файла и
Удаление расшифровки возвращают машиночитаемые коды в
detail.code. Ветвите код по code, а не по тексту сообщения:
| Код | Статус | Значение | Что делать |
|---|---|---|---|
unsupported_file_format | 400 | Расширение не поддерживается | Сверьтесь со списком форматов |
file_too_small | 400 | Меньше 1 КБ | Это не настоящая запись |
filename_required | 400 | Нет заголовка Content-Disposition | Добавьте заголовок |
insufficient_balance | 402 | Минуты закончились | Пополните и загрузите заново |
upload_scope_required | 403 | У ключа нет права загрузки | Создайте ключ с опцией Разрешить загрузку файлов |
delete_scope_required | 403 | У ключа нет права удаления | Создайте ключ с опцией Разрешить удаление расшифровок |
upload_timeout | 408 | Стрим завис / дольше 90 минут | Проверьте соединение, повторите |
idempotency_conflict | 409 | Тот же Idempotency-Key еще грузится | Подождите Retry-After, повторите |
length_required | 411 | Нет Content-Length | Используйте клиент, который его ставит |
file_size_limit_exceeded | 413 | Больше 2 ГБ | Разрежьте или сожмите файл |
too_many_concurrent_uploads | 429 | Лимит параллельных загрузок | Подождите Retry-After, повторите |
too_many_queued_files | 429 | 100+ файлов ждут обработки | Очередь дренируется — подождите, повторите |
upload_quota_exceeded | 429 | Суточный анти-абьюз кап | Повторите после полуночи UTC или напишите в поддержку |
export_quota_exceeded | 429 | Суточный кап объема экспорта | Повторите после полуночи UTC или напишите в поддержку |
uploads_temporarily_disabled | 503 | Загрузки выключены | Временно — повторите позже |
Временные (408, 429, 5xx) → повтор с backoff. Остальные → чините запрос, повтор не поможет.
Никогда не пересылайте файл после 201 — это создаст вторую расшифровку со вторым списанием.
Rate limits
Лимиты — на ключ:
| Поверхность | Лимит |
|---|---|
| Data-эндпоинты (list / get / export / bulk) | 500 запросов / минуту |
| Объем экспорта | 10 ГБ / сутки |
| Загрузка файлов | 60 запросов / минуту, 10 одновременных на ключ |
| Удаления | 30 запросов / минуту |
| Управление ключами | 180 запросов / минуту |
При превышении приходит 429. Обрабатывайте аккуратно:
- Сделайте паузу, не повторяйте сразу. Подождите несколько секунд и попробуйте снова.
- Избегайте плотных циклов. Для экспорта многих расшифровок используйте Массовый экспорт (один запрос) вместо цикла по одиночным экспортам.
- Распределяйте нагрузку вместо сотен вызовов разом.
Не делайте мгновенный авто-ретрай на 429
Немедленные авто-повторы только усугубляют лимит. Используйте экспоненциальный backoff (например, 1s, 2s, 4s).