Claude API 413 `request_too_large`: причины и способы устранения

Ваш вызов к /v1/messages завершается с ошибкой HTTP 413 request_too_large. Эта ошибка связана с сырым размером тела HTTP-запроса в байтах — не с токенами, не с моделью и не с вашим ключом. Ниже разберем, какие действуют лимиты, почему в них упираются запросы с изображениями и PDF и как успешно выполнить задачу.

Короткий ответ

Ошибка 413 request_too_large означает, что тело запроса содержит больше байт, чем принимает эндпоинт. В официальном API Anthropic эндпоинт Messages допускает 128 MB на запрос (Batch — 256 MB, Files API — 500 MB); на облачных платформах лимиты ниже — 20 MB в Amazon Bedrock, 30 MB в Google Cloud под управлением Google, 32 MB в Claude Platform on AWS. Обычно причина кроется в закодированных в base64 изображениях или PDF, которые к тому же пересылаются заново на каждом шаге диалога. Уменьшайте разрешение медиафайлов, загружайте большие файлы один раз через Files API и ссылайтесь на них по file_id, а крупные задачи разбивайте на части. Повторная отправка того же запроса без изменений приведет к той же ошибке.

Симптомы и смысл ошибки

Anthropic документирует тип ошибки и код состояния; приведенный ниже текст сообщения взят из публичных баг-репортов:

json

{
  "type": "error",
  "error": {
    "type": "request_too_large",
    "message": "Request exceeds the maximum size"
  }
}

Согласно странице описания ошибок Anthropic, в официальном API этот ответ возвращает Cloudflare еще до того, как запрос доходит до серверов API — ничего не парсилось, не токенизировалось и не отправлялось в модель. Если перед API стоит ваш собственный обратный прокси, вы можете получить его HTML-страницу ошибки (для nginx это 413 Request Entity Too Large) вообще без JSON.

Не путайте эту ошибку со следующими:

400 "prompt is too long" — слишком много токенов для контекстного окна. Тело запроса, заполненное изображениями, может превысить лимит по байтам при малом числе токенов, и наоборот. См. prompt is too long.
Ошибки, связанные с отдельными изображениями — отдельные проверки размера и разрешения каждого изображения, которые описаны ниже.

Действующие лимиты

По данным обзорной документации и страницы ошибок API Anthropic:

Эндпоинт (официальный Claude API)	Максимальный размер запроса
Messages API	128 MB
Token Counting API	128 MB
Message Batches API	256 MB
Files API (на одну загрузку)	500 MB

На других платформах действуют собственные ограничения: Amazon Bedrock — 20 MB, Claude Models on Google Cloud (Google managed) — 30 MB, а также 32 MB для Messages и Token Counting в Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) и Microsoft Foundry. В старых статьях для Claude также часто встречается цифра «32 MB»; актуальный лимит для официального API составляет 128 MB. Реальным потолком всегда будет наименьший лимит на всем пути следования запроса, включая ваши собственные прокси.

Отдельные правила для каждого изображения из документации Anthropic по работе с изображениями (vision):

До 10 MB на изображение (в кодировке base64) в Claude API; 5 MB в Bedrock.
Максимальное разрешение 8000×8000 px. Если запрос содержит более 20 изображений, применяется более строгий лимит на разрешение каждого из них; Anthropic рекомендует ограничивать обе стороны до 3,000 px или оставлять в запросе не более 20 блоков с изображениями и документами.
До 600 изображений или страниц PDF на запрос (100 для моделей с контекстом 200K). Anthropic предупреждает, что вы можете упереться в общий лимит размера запроса раньше, чем достигнете 600.

Почему это происходит

Накладные расходы Base64. Base64 превращает каждые 3 байта в 4 символа, поэтому PDF-файл размером 9 MB превращается примерно в 12 MB JSON.
Повторная пересылка истории. Каждый запрос передает всю историю диалога целиком; как отмечается в руководстве Anthropic по vision, изображения в base64 пересылаются на каждом шаге. Чат с несколькими скриншотами разрастается, пока не перешагнет лимит — обычно прямо в середине сессии.
Скриншоты агентов. Агенты для управления компьютером (computer-use) и браузером возвращают изображение в tool_result на каждом шаге.
Оригиналы в полном разрешении. Фотографии с телефонов и скриншоты с Retina-экранов отправляются в исходном размере, хотя Claude все равно уменьшает изображения, превышающие его нативное разрешение.
Более низкий лимит на промежуточном узле. В nginx значение client_max_body_size по умолчанию равно 1 MB; у бессерверных (serverless) платформ и API-шлюзов тоже есть свои ограничения на размер полезной нагрузки.

Решение 1: Измерьте размер полезной нагрузки

Проверяйте точный размер отправляемых байт, а не размер файла на диске:

python

import json

body = {"model": "claude-sonnet-5-5", "max_tokens": 1024, "messages": messages}
size_mb = len(json.dumps(body).encode("utf-8")) / 1_000_000
print(f"request body: {size_mb:.1f} MB")
if size_mb > 100:   # оставляем запас до лимита официального API в 128 MB
    raise ValueError("request too large: downscale, use file_id, or split")

Запускайте эту проверку непосредственно перед вызовом API в цикле вашего агента. Если размер растет от шага к шагу, причина в истории диалога (Решение 4), а не в одном большом файле.

Решение 2: Уменьшайте разрешение и сжимайте изображения перед кодированием

Отправка 12-мегапиксельной фотографии ничего не дает, если модель все равно уменьшит ее разрешение, но при этом тратит байты на каждом шаге. Сначала измените размер:

python

import base64, io
from PIL import Image

def encode_image(path, max_side=2000, quality=85):
    img = Image.open(path)
    img.thumbnail((max_side, max_side))          # сохраняет пропорции
    buf = io.BytesIO()
    img.convert("RGB").save(buf, format="JPEG", quality=quality)
    return base64.standard_b64encode(buf.getvalue()).decode()

Значения max_side=2000 и качество JPEG 85 — это отправная точка, а не официальные константы; сверьтесь со страницей документации Anthropic по vision, чтобы узнать нативное разрешение используемой вами модели, и не превышайте 3,000 px по каждой стороне, если в запросе более 20 изображений. Для скриншотов с мелким текстом оставляйте формат PNG, если артефакты JPEG ухудшают читаемость. Для агентов computer-use и browser-use изменение размера обязательно: Anthropic отклоняет слишком большой скриншот в tool_result с ошибкой валидации, а не уменьшает его автоматически.

Решение 3: Загрузите файл один раз через Files API

Files API создан именно для этого. Вы загружаете файл один раз, получаете file_id и ссылаетесь на него в запросах к Messages вместо встраивания base64. Он вышел из беты и не требует beta-заголовка, размер каждого файла может достигать 500 MB, а сами файловые операции бесплатны (содержимое файла, использованное в запросе, тарифицируется как входные токены).

bash

# 1. Загрузка
curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@report.pdf"
# => {"id": "file_011CNha8iCJcU1wXNR6q4V8w", ...}

# 2. Ссылка на файл
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": [
      {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}},
      {"type": "text", "text": "Summarize the key findings."}
    ]}]
  }'

Что важно учитывать перед использованием:

Доступность. Поддерживается в Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) и Microsoft Foundry (размещенном на стороне Anthropic). Bedrock и Claude Models on Google Cloud (Google managed) принимают изображения и PDF только в формате base64.
Область видимости. Файлы принадлежат рабочему пространству (workspace), в которое они были загружены, и любой ключ в этом пространстве может их прочитать. Никогда не принимайте значения file_id от конечных пользователей.
Это не уменьшает количество токенов. Содержимое по-прежнему учитывается в контекстном окне, поэтому огромный текстовый файл все так же может вызвать ошибку "prompt is too long".

На изображения и PDF также можно ссылаться через источник типа url — тогда Anthropic скачает их сам, и вам не придется встраивать байты в запрос.

Решение 4: Не пересылайте устаревшие медиафайлы и разбивайте крупные задачи

Очищайте историю. После того как Claude описал скриншот, замените старый блок image в сохраненной истории на короткую текстовую заметку. Никогда не удаляйте сам блок tool_result, иначе вы вызовете ошибку tool_use without tool_result — просто замените изображение внутри него на текст.
Разбивайте PDF. Обрабатывайте длинный документ по диапазонам страниц и объединяйте полученные ответы.
Проверьте собственные промежуточные узлы. Увеличьте client_max_body_size в nginx и проверьте лимиты на размер тела запроса на промежуточных serverless-платформах и API-шлюзах.

Ошибка 413 детерминирована: одно и то же тело запроса будет вызывать сбой каждый раз, поэтому повторяйте запрос только после изменения полезной нагрузки. Если агентский фреймворк продолжает пересылать одну и ту же раздутую историю, начните новую сессию или удалите вложение из истории.

Если вы вызываете Claude через byesu

byesu — это шлюз AI API с OpenAI-совместимым эндпоинтом (https://byesu.com/v1) и нативным эндпоинтом Anthropic (/v1/messages на том же хосте) с оплатой по мере использования (pay-as-you-go) без подписки. Здесь важны два момента:

file_id не переносится между сервисами. Файлы привязаны к рабочему пространству Anthropic, в которое они были загружены, поэтому идентификатор из вашего собственного аккаунта Anthropic не имеет смысла для любого другого сервиса. При работе через byesu поддерживайте компактный размер запросов за счет сжатия медиафайлов перед кодированием в base64 (Решение 2) и очистки истории (Решение 4).
На обоих эндпоинтах работает одна и та же арифметика. В /v1/chat/completions поле image_url с data: URI — это тоже base64, поэтому накладные расходы 4/3 и рост объема при пересылке на каждом шаге действуют точно так же. Измеряйте тело запроса с помощью фрагмента кода из Решения 1 независимо от используемого формата.

Чтобы начать работу, создайте токен в консоли, направьте ваш SDK на указанный выше эндпоинт и укажите идентификатор модели, например claude-sonnet-5-5. Полная инструкция по настройке: Быстрый старт.

FAQ

Что означает ошибка Claude API 413 request_too_large?

Она означает, что тело HTTP-запроса содержит больше байт, чем принимает эндпоинт. Это проверка сырого размера полезной нагрузки, а не количества токенов или контекстного окна, и в официальном API Anthropic этот ответ возвращает Cloudflare еще до того, как запрос доходит до серверов API. Одно и то же тело запроса будет отклоняться каждый раз, поэтому перед повторной попыткой запрос нужно уменьшить.

Каков максимальный размер запроса к Claude API?

В официальном API Anthropic запросы к Messages и Token Counting могут быть до 128 MB, запросы к Message Batches — до 256 MB, а загрузка через Files API — до 500 MB на файл. На других платформах лимиты ниже: Amazon Bedrock — 20 MB, Claude Models on Google Cloud (Google managed) — 30 MB, и 32 MB для Messages на Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) и Microsoft Foundry.

Ошибка 413 request_too_large — это то же самое, что "prompt is too long"?

Нет. Ошибка 413 request_too_large связана с количеством байт в теле HTTP-запроса, обычно из-за изображений или PDF в формате base64. А "prompt is too long" — это ошибка 400, означающая, что количество токенов превысило контекстное окно модели. Запрос может не пройти любую из этих проверок независимо от другой, и решаются они по-разному: для 413 нужно сжать или выгрузить медиафайлы, а для "prompt is too long" — сократить или суммаризировать контент.

Как отправлять большие изображения или PDF в Claude без ошибки 413?

Уменьшайте разрешение и сжимайте изображения перед кодированием в base64, а большие файлы загружайте один раз через Files API и затем ссылайтесь на них по file_id в блоке document или image. Также удаляйте старые медиафайлы в base64 из истории диалога, поскольку каждый запрос пересылает всю историю целиком, и разбивайте очень длинные PDF на диапазоны страниц.

Стоит ли повторять запрос при ошибке 413?

Без изменений — нет. Ошибка 413 детерминирована, поэтому одна и та же полезная нагрузка будет вызывать сбой каждый раз, а слепые повторы только тратят время. Измерьте размер тела запроса, сожмите или вынесите медиафайлы, а затем отправьте запрос снова. Если ошибку возвращает ваш собственный прокси (например, стандартный client_max_body_size в 1 MB в nginx), вместо этого увеличьте лимит на нем.

Claude API 413 request_too_large: причины и способы устранения ​

Симптомы и смысл ошибки ​

Действующие лимиты ​

Почему это происходит ​

Решение 1: Измерьте размер полезной нагрузки ​

Решение 2: Уменьшайте разрешение и сжимайте изображения перед кодированием ​

Решение 3: Загрузите файл один раз через Files API ​

Решение 4: Не пересылайте устаревшие медиафайлы и разбивайте крупные задачи ​

Если вы вызываете Claude через byesu ​

FAQ ​

Что означает ошибка Claude API 413 request_too_large? ​

Каков максимальный размер запроса к Claude API? ​

Ошибка 413 request_too_large — это то же самое, что "prompt is too long"? ​

Как отправлять большие изображения или PDF в Claude без ошибки 413? ​

Стоит ли повторять запрос при ошибке 413? ​