Ошибка 412 при загрузке видео в MAX: причины и решение

При попытке отправить видеофайл в мессенджер MAX через API разработчики часто сталкиваются с HTTP 412 Precondition Failed. Эта ошибка указывает на невыполнение предварительных условий, заданных сервером. В этой статье мы подробно разберём, почему возникает статус 412, какие заголовки необходимо добавить для корректной передачи данных и как реализовать возобновляемую загрузку при обрыве соединения.

Что означает ошибка 412 Precondition Failed?

Код 412 Precondition Failed возвращается, когда сервер не может выполнить одно или несколько условий, указанных в заголовках запроса. Чаще всего это связано с неправильной работой условных заголовков, таких как If-Match, If-None-Match, If-Modified-Since или Content-Range. В контексте загрузки видео в MAX сервер может требовать определённые метаданные или корректный размер чанка.

Основные причины ошибки 412 при отправке видео

Отсутствие обязательных заголовков

В вашем коде используется только Authorization. Для работы с API MAX могут потребоваться дополнительные заголовки:

• Content-Type - обычно application/octet-stream для бинарных данных.
• Content-Length - точный размер отправляемого тела (обязателен, если не используется chunked transfer).
• Content-Range - нужен для дозагрузки (resumable upload).
• X-Upload-Content-Type - исходный MIME-тип файла, например video/mp4.
• X-Upload-Content-Length - общий размер видео.

Некорректный токен или сессия

Вы получаете URL для загрузки через POST-запрос, но не передаёте полученный token в последующем запросе. Сервер может проверять его как часть предварительного условия. Убедитесь, что токен включён в заголовки или тело запроса, как того требует документация.

Проблемы с размером чанка

Вы читаете файл по 1 МБ, но не указываете Content-Range. Без этого сервер не может проверить, какой именно фрагмент вы отправляете, и возвращает 412. Для возобновляемой загрузки обязательно указывайте диапазон байтов.

Как исправить ошибку: правильные заголовки для загрузки видео

Для успешной отправки видеофайла в MAX добавьте следующие заголовки в POST-запрос:

headers = {
    'Authorization': TOKEN,
    'Content-Type': 'application/octet-stream',
    'Content-Length': str(total_size),
    'X-Upload-Content-Type': 'video/mp4',
    'X-Upload-Content-Length': str(total_size)
}

Если вы используете чанкованную передачу (chunked), уберите Content-Length и добавьте Transfer-Encoding: chunked. Однако для дозагрузки лучше применять Content-Range.

Реализация возобновляемой загрузки (resumable upload)

Чтобы видео догружалось после обрыва, нужно:

• Сначала узнать, сколько байт уже принято сервером (через GET-запрос к URL загрузки с заголовком Range: bytes=0-).
• Затем отправить оставшуюся часть с заголовком Content-Range: bytes start-end/total.
• Обрабатывать ответы с кодом 308 Resume Incomplete (стандарт для возобновляемых загрузок).

Пример функции с дозагрузкой:

def upload_video_resumable(video_path, upload_url):
    total_size = os.path.getsize(video_path)
    # Проверяем прогресс
    head_resp = requests.head(upload_url)
    uploaded = int(head_resp.headers.get('X-Uploaded-Bytes', 0))
    
    with open(video_path, 'rb') as f:
        f.seek(uploaded)
        headers = {
            'Authorization': TOKEN,
            'Content-Range': f'bytes {uploaded}-{total_size-1}/{total_size}'
        }
        while True:
            chunk = f.read(1024 * 1024)
            if not chunk:
                break
            resp = requests.put(upload_url, data=chunk, headers=headers)
            if resp.status_code in [200, 201, 308]:
                # обновляем прогресс
                pass
            else:
                print(f'Ошибка: {resp.status_code}')
                break
    return resp.json().get('token')

Проверка токена и статуса загрузки

Если видео не появляется даже спустя неделю, проблема может быть в том, что токен не активируется после завершения загрузки. После успешной отправки всех байтов отправьте финальный POST-запрос на эндпоинт подтверждения, указав полученный токен. Внимательно изучите документацию MAX: возможно, требуется отправить метаданные (название, описание) отдельным запросом.

Пошаговый план исправления ошибки 412

1. Проверьте актуальность токена авторизации.
2. Добавьте заголовки Content-Type, Content-Length и X-Upload-Content-Type.
3. Реализуйте дозагрузку с Content-Range и обработкой кода 308.
4. После завершения отправки подтвердите токен через отдельный запрос.
5. Протестируйте с маленьким файлом (1-5 МБ) для отладки.

Следуя этим рекомендациям, вы избавитесь от ошибки 412 и сможете надёжно загружать видео любого размера в MAX.