Payload Too Large
payload_too_large413
Request body exceeded the 64KB size limit. Trim the payload or split into multiple requests.
What this means
The request body was larger than the 64KB ceiling we enforce on incoming payloads. We check size before parsing the body, so the request was rejected without even attempting JSON validation. No business logic ran; nothing happened on our side beyond the size check.
When you'll see this
- A batch operation packed too many items into a single request body.
- A request inadvertently included a base64-encoded blob (an image, document) where structured data was expected.
- A development tool serialized far more state than intended (full snapshots in place of deltas).
- An automated pipeline misformed a payload and produced a runaway-sized output.
Learn more about how this works
The 64KB limit exists to protect the platform from runaway payloads and to keep response times predictable. Most Asterwise endpoints work with structured, compact data — birth details, plan IDs, query parameters. Even the largest legitimate payloads (transit ranges, batch chart requests) fit comfortably under 64KB when properly serialized.
In practice: if you're hitting this, something is off in how you're constructing the request. Asterwise endpoints don't accept large blobs (images, PDFs, raw documents) by design — those don't belong in API calls. If you find yourself with a 64KB+ payload, the right move is almost always to restructure, not to lobby for a larger limit.
Example response
{
"success": false,
"error": "payload_too_large",
"message": "Request body exceeds maximum allowed size of 64KB.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/payload_too_large",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Reduce the size of the request body. Most overruns are caused by unnecessary fields or oversized content.
- If you're batching items, split into smaller batches and send multiple requests.
- If a blob is in your payload that shouldn't be there (image, document, binary data), remove it.
Validate payload size before sending. Don't try to recover after the fact — restructure on your side.
Python:
Production handler
- Python
- TypeScript
import httpx
import json
MAX_BODY_BYTES = 64 * 1024
def call_asterwise(url, headers, payload):
serialized = json.dumps(payload)
if len(serialized.encode()) > MAX_BODY_BYTES:
raise ValueError(
f"Payload size {len(serialized)} bytes exceeds 64KB limit. "
f"Reduce or split the request."
)
response = httpx.post(url, headers=headers, content=serialized, timeout=30)
response.raise_for_status()
return response.json()
const MAX_BODY_BYTES = 64 * 1024;
async function callAsterwise(url: string, headers: HeadersInit, payload: unknown) {
const serialized = JSON.stringify(payload);
const byteLen = new TextEncoder().encode(serialized).length;
if (byteLen > MAX_BODY_BYTES) {
throw new Error(
`Payload size ${byteLen} bytes exceeds 64KB limit. ` +
`Reduce or split the request.`,
);
}
const response = await fetch(url, {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: serialized,
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
Avoid this error by
- Pre-flight payload size in your client code. Reject locally rather than wasting a round-trip.
- Never include blobs (images, documents, binary data) in API request bodies. Asterwise endpoints work with structured data only.
- For batch operations, choose batch sizes that comfortably fit under the limit. 10-50 items per batch is usually safe.
- Use streaming or pagination for large data sets rather than packing everything into one request.