Migration API Mutation Error: Request Body Exceeds Limit of 4000000 Bytes

You're hitting Sanity's 4MB request body limit for mutation API requests, which is a hard limit documented in their technical limits. When migrating data with large portable text fields, here are your workaround options:

1. Split Documents into Smaller Chunks (Recommended)

Break your large documents into smaller pieces before importing. For portable text specifically, you can:

• Split long portable text arrays into multiple fields or related documents
• Use transactions to batch multiple smaller mutations together (keeping each transaction under 4MB)
• Process documents in batches with proper rate limiting (25 requests/second max)

Example using the Sanity client with batching:

const {default: PQueue} = require('p-queue')
const queue = new PQueue({
  concurrency: 1,
  interval: 1000 / 25  // Stay under 25 req/s rate limit
})

// Split large documents and queue them
largeDocs.forEach(doc => {
  queue.add(() => client.create(doc))
})

2. Use the NDJSON Import Tool

The CLI import tool (sanity dataset import) is designed for bulk operations and may handle large documents more efficiently than direct API mutations:

sanity dataset import my-data.ndjson production --replace

However, individual documents still can't exceed the 32MB document size limit.

3. Compress Your Requests

While not explicitly documented, you could try using gzip compression with the Content-Encoding: gzip header on your mutation requests. This might help if your portable text is highly compressible, though the 4MB limit likely applies to the uncompressed payload.

4. Restructure Your Content Model

Consider if your portable text fields are too large and should be split into:

• Multiple related documents with references
• Paginated content blocks
• Separate content fragments

Key Constraints to Remember

• Maximum mutation request body: 4MB
• Maximum document size: 32MB
• API rate limit: 25 mutations/second per IP
• Transaction payload: Keep under 500KB for best performance

The transactions documentation recommends keeping transaction payloads reasonable and using throttling libraries like p-throttle for bulk operations.

If you're doing a one-time migration, the NDJSON import approach is your best bet. For ongoing operations, you'll need to architect your content to stay within these limits.