Skip to main content

batch_too_large

The emails array is outside the size a single batch accepts. None of the messages in it were sent, and nothing was charged.

Status: 422

{
  "status": 422,
  "type": "batch_too_large",
  "message": "The emails array must contain between 1 and 100 items",
  "request_id": "req_01J8K2P...",
  "doc_url": "https://docs.epostix.com/errors/batch_too_large"
}

Why you got this​

  • The array holds more than 100 items.
  • The array is empty, usually because the list you built it from filtered down to nothing.
  • Your chunking is off by one and emits 101 items per group.
  • A retry merged two pending chunks into one request.

How to fix it​

Split the send into groups of 100 or fewer and send them as separate requests. Give each batch its own Idempotency-Key so a retry replays that batch rather than sending it twice, and check the response of each one before moving to the next.

Size is not the only per-request limit. The whole body still has to fit, attachments across the request total at most 40MB, and the request rate applies to the workspace as a whole, so firing every chunk at once can turn into rate_limit_exceeded. See rate limits for the headers that tell you how much room is left.

Is it safe to retry​

No, not unchanged. Rebuild the request as correctly sized batches and send those.

Reusing the Idempotency-Key from the rejected request is safe, because a batch rejected on size was never stored.