stalwartlabs/stalwart · error · ScimError

The number of operations in the bulk request exceeds the max

Error message

The number of operations in the bulk request exceeds the maxOperations ({max_operations}).

What it means

A SCIM Error with status 413 built by `Error::max_operations_exceeded(max_operations)`. It is thrown when a SCIM bulk request contains more operations than the server's configured maxOperations limit, and the detail message states the configured maximum.

Source

Thrown at crates/scim-proto/src/message/error.rs:183

    pub fn forbidden(detail: impl Into<Cow<'static, str>>) -> Self {
        Error::new(403).with_detail(detail)
    }

    pub fn not_found() -> Self {
        Error::new(404)
    }

    pub fn conflict(detail: impl Into<Cow<'static, str>>) -> Self {
        Error::new(409).with_detail(detail)
    }

    pub fn precondition_failed() -> Self {
        Error::new(412)
    }

    pub fn max_operations_exceeded(max_operations: usize) -> Self {
        Error::new(413).with_detail(format!(
            "The number of operations in the bulk request exceeds the maxOperations ({max_operations})."
        ))
    }

    pub fn max_payload_size_exceeded(max_payload_size: usize) -> Self {
        Error::new(413).with_detail(format!(
            "The size of the bulk operation exceeds the maxPayloadSize ({max_payload_size})."
        ))
    }

    pub fn internal_error() -> Self {
        Error::new(500)
    }

    pub fn not_implemented() -> Self {
        Error::new(501)
    }

View on GitHub (pinned to e962003857)

Solutions

Split the bulk request into chunks of at most maxOperations operations each.
Read the server's /ServiceProviderConfig (bulk.maxOperations) and size batches accordingly before sending.
Reduce batch size in the integration's configuration and re-run the sync.

Example fix

// before
client.bulk(all_operations).await?; // 5000 ops
// after
for chunk in all_operations.chunks(max_operations) {
    client.bulk(chunk.to_vec()).await?;
}

Defensive patterns

Strategy: validation

Validate before calling

let cfg = client.service_provider_config().await?;
let max_ops = cfg.bulk.as_ref().map(|b| b.max_operations).unwrap_or(default);
assert!(operations.len() <= max_ops, "split bulk request: {} > {}", operations.len(), max_ops);

Prevention

Read bulk.maxOperations from /ServiceProviderConfig before batching.
Chunk bulk operations defensively with a margin below the limit.
Re-check limits after server upgrades or provider migrations.

When it happens

Trigger: Submitting a POST to /Bulk whose "Operations" array length exceeds the server's maxOperations configuration, triggering this constructor with that limit.

Common situations: Large initial provisioning syncs batch thousands of users into one bulk request; the server was reconfigured to a lower maxOperations while clients still send big batches; copying an integration between servers with different bulk limits.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

AI-assisted analysis of stalwartlabs/stalwart@e962003857 (2026-09-06). Data as JSON: /api/errors/db6238f177c581fa. Report an issue: GitHub.