Amazon SNS Message Size Limit: 256 KB Payload Caps, Protocols, and Large Payloads

The Amazon SNS message size limit is a fixed quota of 256 KB (262,144 bytes) for published message payloads across all supported delivery protocols including HTTP/S, SQS, Lambda, and email. When an application publishes a message whose combined body and attributes exceed this threshold, Amazon SNS rejects the request with an InvalidParameter error. While AWS allows topics to expand up to 1 MiB (1,048,576 bytes) by setting the MaximumMessageSize attribute, doing so introduces strict operational constraints: the topic is capped at 100 subscriptions and can only deliver to Amazon SQS, AWS Lambda, or Amazon Data Firehose endpoints.

What Counts Toward the 256 KB Quota

The 256 KB quota applies to the total byte volume of the published request:

1. The Message Body: The raw string submitted in the Message parameter, whether formatted as plaintext, JSON, XML, or base64-encoded binary.
2. Message Attributes: Structured metadata pairs attached in MessageAttributes. Amazon SNS sums the byte length of each attribute name, data type declaration (String, Number, or Binary), and attribute value.

Total Payload Bytes = Length(Message Body) + Sum(Length(Name) + Length(Type) + Length(Value))

If message attributes contain routing identifiers and timestamps, those metadata bytes directly consume part of your 262,144 byte allowance. If the combined sum reaches 262,145 bytes, Amazon SNS refuses the request.

The InvalidParameter Error Syntax

When an application exceeds the quota, Amazon SNS rejects the call synchronously with an HTTP 400 Bad Request response:

<ErrorResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
  <Error>
    <Type>Sender</Type>
    <Code>InvalidParameter</Code>
    <Message>Invalid parameter: Message too long</Message>
  </Error>
  <RequestId>7b4a8e29-18c2-5d34-912f-689e24b7a102</RequestId>
</ErrorResponse>

In the AWS SDK for Python (boto3), this surfaces as a botocore.exceptions.ClientError with code InvalidParameter. The message never enters the topic, no subscriber receives an alert, and no dead-letter queue records the drop because rejection occurs prior to ingestion.

Amazon SNS Billing Chunks

Amazon SNS meters API requests based on payload size in 64 KiB increments:

Publishing large messages near the cap increases request metering costs compared to publishing compact event notifications.

Protocol Limits and Payload Delivery Behavior

While topics accept 256 KB by default, downstream subscriber protocols enforce their own delivery constraints:

Mobile push and SMS endpoints enforce practical limits far below the 256 KB topic quota. When broadcasting across mixed subscription types, the lowest common denominator dictates acceptable payload size.

• DynamoDB Item Size Limit: The 400 KB Cap, ValidationException, and Storage PatternsThe DynamoDB item size limit is a strict maximum of 400 KB per item, calculated by summing the byte lengths of all...
• Kafka Message Size Limits: Broker Caps, Configuration, and the Claim-Check PatternApache Kafka enforces a default message size limit of 1,048,576 bytes (1 MB) across broker, producer, and consumer...
• OneDrive Agent: Connecting AI Agents to OneDrive File StorageAn OneDrive agent connects autonomous AI models to cloud file storage, allowing systems like Claude and Cursor to...
• NATS Message Size Limit: Configuring Max Payload and Handling Large PayloadsThe default NATS message size limit is `1 MB` (`1,048,576` bytes), defined by the server `max_payload` setting across...
• RabbitMQ Message Size Limit: Handling Large Payloads and Agent WorkflowsThe RabbitMQ message size limit defaults to 16 MiB in RabbitMQ version 4 and later, and 128 MiB in versions 3.8 through...
• AWS Strands Agents: Build AI Agents with Amazon's Agent FrameworkAWS Strands Agents is Amazon's open-source Python framework for building AI agents that use tools, maintain memory, and...

More on this subject: AI Agents: General Guides (172 guides)

Amazon SNS provides the MaximumMessageSize attribute, allowing administrators to configure topic payload allowances anywhere from 1,024 bytes (1 KiB) up to 1,048,576 bytes (1 MiB). By default, all existing and newly created topics remain at 262,144 bytes (256 KiB) unless modified.

Operational Constraints Above 256 KB

Raising MaximumMessageSize beyond 256 KB transforms the topic into a specialized transport channel. AWS enforces three operational restrictions once a topic exceeds 256 KB:

1. Subscription Count Cap: The topic supports a maximum of 100 total subscriptions. Attempting to add a 101st subscription returns an InvalidParameter error.
2. Restricted Endpoint Types: Only three subscriber protocols are permitted: Amazon SQS, AWS Lambda, and Amazon Data Firehose.
3. Incompatible with Public Endpoints: If a topic currently holds any HTTP/HTTPS, SMS, email, email-json, or mobile push subscriptions, AWS refuses requests to increase MaximumMessageSize above 256 KB.

To send larger payloads across microservices, you must isolate those flows into dedicated topics subscribed exclusively to internal queues or compute functions.

Modifying MaximumMessageSize with the AWS CLI

You can configure MaximumMessageSize during topic creation or update existing topics using the AWS Command Line Interface.

To create a new topic configured for 1 MiB payloads:

aws sns create-topic \
  --name agent-artifact-events \
  --attributes MaximumMessageSize=1048576

To update an existing topic from 256 KB to 1 MiB:

aws sns set-topic-attributes \
  --topic-arn arn:aws:sns:us-east-1:123456789012:agent-artifact-events \
  --attribute-name MaximumMessageSize \
  --attribute-value 1048576

Verify your topic's current MaximumMessageSize using aws sns get-topic-attributes. If the attribute has not been explicitly set, it does not appear in the response, and the topic uses the default of 262,144 bytes (256 KiB).

Downstream Endpoint Boundaries and Delivery Gotchas

Configuring an SNS topic to 1 MiB does not guarantee that downstream subscribers can process the payload without error:

• Amazon Data Firehose Buffer Mismatch: Amazon Data Firehose enforces a record limit of 1,000 KiB (1,024,000 bytes). When Amazon SNS delivers a message to Firehose, it wraps the message in delivery metadata, including the message ID, topic ARN, and timestamp. If an application publishes a 1,024 KiB payload to an SNS topic, the combined message and metadata will exceed Firehose's 1,000 KiB limit, causing delivery to fail. For Firehose subscriptions, set MaximumMessageSize below 1,000 KiB.
• AWS Lambda Invocations: AWS Lambda supports asynchronous invocation payloads up to 1 MiB. Because SNS invokes Lambda asynchronously, a 1 MiB SNS message matches Lambda's input limit.
• Amazon SQS Queue Overrides: Standard Amazon SQS queues feature a default MaximumMessageSize of 256 KB. However, when an SQS queue subscribes to an expanded SNS topic, the SNS topic attribute governs delivery. SQS accepts the expanded payload from SNS without requiring separate queue attribute modification.

Configure an Amazon SQS dead-letter queue (DLQ) on each subscription to capture failed deliveries. Monitor delivery health in Amazon CloudWatch using the NumberOfNotificationsFailed metric.

Publishing multi-megabyte files directly through a publish/subscribe broker creates systemic bottlenecks. High payload volumes saturate network sockets, increase JSON serialization overhead, and inflate cloud messaging bills. When application payloads exceed 1 MiB, or when distributing documents, datasets, and media files, systems implement the Claim-Check Pattern.

How the Claim-Check Pattern Works

The Claim-Check Pattern decouples notification signaling from payload transmission:

1. Store the Artifact: The publishing service uploads the raw file into a durable storage store.
2. Generate the Claim Check: The storage service returns an immutable reference, such as an object key, file identifier, or content URI, along with metadata (size, MIME type, hash).
3. Publish Lightweight Notification: The producer publishes a compact JSON message to Amazon SNS containing only the claim check reference. The resulting notification JSON remains lightweight, consuming minimal network bandwidth.
4. Retrieve on Demand: Subscribing services receive the notification, evaluate whether they need the full file, and use the claim check pointer to stream the artifact directly from storage.

Producer ----(1) Store Large Artifact-------------> Storage Layer
   |                                                    ^
   +--------(2) Publish Claim Check (Lightweight)       |
                    |                                   |
                    v                                   |
                Amazon SNS                              |
                    |                                   |
   +----------------+----------------+                  |
   |                                 |                  |
   v                                 v                  |
Consumer A (Worker)              Consumer B (Audit)     |
   |                                 |                  |
   +--(3) Fetch Data via Pointer-----+------------------+

The S3 Extended Client Library Approach

AWS provides an implementation of this pattern through the Amazon SNS Extended Client Library for Java and Python. These client libraries integrate Amazon S3 with Amazon SNS:

• When publishing a message, the library checks if the payload exceeds a user-defined threshold.
• If the message exceeds the threshold, the library uploads the payload to a configured S3 bucket and replaces the SNS message body with an S3 object pointer.
• When an SQS subscriber reads the message, the corresponding SQS Extended Client Library detects the pointer, downloads the payload from S3, and returns the original message body to the application.
• The Extended Client supports large message payloads through automated S3 object references.

While effective for Java and Python microservices within AWS, the S3 Extended Client presents distinct architectural limitations:

• SDK Lock-in: The automated hydration logic exists only in official AWS Java and Python libraries. Other runtimes, such as Go, Node.js, or external webhook consumers, must write custom logic to detect S3 pointer schemas and handle authentication.
• Unstructured Object Storage: Amazon S3 stores raw bytes. It does not index file contents for semantic search, provide document data extraction, or offer real-time collaboration.
• Operational Cleanup Overhead: Applications must configure S3 lifecycle rules to delete old payload objects. If an SNS notification fails to process or an SQS consumer deletes a message prematurely, orphaned payload objects accumulate in S3.

Publishing Claim-Check Notifications in Python

When building modular architectures, publishing explicit claim checks using standard AWS SDKs is cleaner than relying on automated client wrappers:

import json
import hashlib
import boto3

sns = boto3.client("sns", region_name="us-east-1")

def publish_claim_check(topic_arn: str, file_uri: str, file_bytes: bytes, filename: str):
    file_size = len(file_bytes)
    file_hash = hashlib.sha256(file_bytes).hexdigest()
    
    notification_payload = {
        "event_version": "1.0",
        "event_type": "artifact.created",
        "resource": {
            "name": filename,
            "uri": file_uri,
            "byte_size": file_size,
            "checksum_sha256": file_hash,
            "mime_type": "application/pdf"
        }
    }
    
    response = sns.publish(
        TopicArn=topic_arn,
        Message=json.dumps(notification_payload),
        Subject="ArtifactReady",
        MessageAttributes={
            "EventType": {
                "DataType": "String",
                "StringValue": "artifact.created"
            },
            "PayloadSize": {
                "DataType": "Number",
                "StringValue": str(file_size)
            }
        }
    )
    return response["MessageId"]

This pattern keeps the SNS message body compact, minimizing messaging costs while allowing downstream services to decide how and when to retrieve the underlying file.

As engineering teams deploy autonomous AI agents for automated research, code auditing, and data extraction, messaging payloads change character. Autonomous agents do not merely exchange short status strings; they generate multi-page PDF audits, complex JSON graphs, full repository diffs, and tabular datasets.

Piping rich agent artifacts directly through Amazon SNS event bodies causes immediate failures:

• Payloads quickly blow past the 256 KB default limit and the 1 MiB topic maximum.
• Subscribing agents consume massive token volumes attempting to parse multi-megabyte text payloads directly in prompt context.
• Platform attachment limits restrict direct ingestion. As documented by the Claude Help Center, Claude chat sessions accept up to 20 files at up to 500 MB per file, while Claude Projects accept files up to 30 MB each with no fixed file-count cap, bounded only by the model's context window.

When multi-agent pipelines attempt to circulate dense documents through notification payloads, context windows saturate and latency multiplies.

The Intelligent Workspace as an Artifact Substrate

Production agent architectures resolve this bottleneck by decoupling event notifications from artifact storage. The notification broker handles lightweight routing alerts, while an intelligent workspace handles file storage, indexing, and retrieval.

In this architecture, autonomous agents and backend services store artifacts in org-owned Fast.io workspaces. Fast.io provides persistent cloud workspaces with chunked upload mechanics supporting large files across organization tiers. Data teams can import files once or connect folders using Cloud Sync for Google Drive, Dropbox, Box, and OneDrive (operating on a configured schedule or on demand, never continuous or real-time).

Once a file lands in a workspace, enabling Intelligence Mode automatically indexes the document across full-text, semantic vectors, and metadata values. Rather than serializing multi-megabyte PDF documents into an SNS message or attaching them to an LLM prompt, the producer saves the file to Fast.io and publishes a claim check with the workspace identifier.

Querying Workspace Files via the Model Context Protocol

Subscribing AI agents, such as Claude Code, Cursor, Codex, or OpenClaw, do not need to download the full file to local memory. Instead, the agent connects to Fast.io through the remote Model Context Protocol (MCP) server over Streamable HTTP:

• Use https://mcp.fast.io/mcp/tools for Claude applications and general MCP clients.
• Use https://mcp.fast.io/mcp/operations for ChatGPT and Codex (after the Fastio plugin).
• Use https://mcp.fast.io/mcp/code for coding agents like Claude Code, Cursor, and Gemini CLI.

Setup documentation is available at https://mcp.fast.io/docs, with tool surface specifications at https://mcp.fast.io/skill.md.

When the agent receives an SNS alert containing a workspace file reference, it queries the workspace through the consolidated MCP storage read tool using the search action:

{
  "method": "tools/call",
  "params": {
    "name": "storage",
    "arguments": {
      "action": "search",
      "search": "reconciliation variance in European division accounts",
      "files_scope": ["audit-report-2026-q3.pdf"]
    }
  }
}

The workspace searches the indexed document and returns only the precise paragraphs matching the inquiry, complete with citations. An operation that would have consumed massive prompt context if passed through an event stream consumes only a few paragraphs of focused context. Writes, moves, and deletions use the companion storage_manage tool.

Structured Extraction with Metadata Views

When event-driven pipelines generate recurring document batches, such as vendor agreements or claim forms, converting text into structured data using ad-hoc prompts creates schema drift.

Fast.io resolves this through Metadata Views. Metadata Views turn unstructured documents into live, queryable databases. Users describe the fields they want extracted in natural language, and AI designs a typed schema across Text, Integer, Decimal, Boolean, URL, JSON, and Date & Time. Autonomous agents can create Views, trigger extraction, and query structured records directly through MCP without managing custom parsing scripts.

Multi-Agent Versioning and Audit Controls

When multiple agents collaborate across an event-driven pipeline, file consistency requires governance:

• Per-File Version History: Every document write in a workspace generates an immutable version record. If an agent overwrites an analysis or reformats a document, prior states remain recoverable.
• Append-Only Audit Log: Every file read, search query, share generation, and modification is recorded in an immutable audit log, establishing clear attribution across human and automated actions.
• Ownership Transfer: An autonomous agent can programmatically provision an organization and workspace, configure folder hierarchies, and transfer administrative ownership to human stakeholders while maintaining operational access.
• Workspace Events Feed: To react to changes without external webhook configurations, services can subscribe to the Fast.io workspace activity feed over WebSocket or long-polling (GET /current/activity/poll/{entity_id}?wait=95&lastactivity={timestamp}).

Decouple Agent Artifacts from Message Size Limits

Connect Claude, Cursor, and event-driven agents to Fast.io workspaces over MCP. Store multi-gigabyte files beyond messaging broker caps, index documents automatically for hybrid search, and query structured data with source citations. Monthly plans start with a 14-day free trial.

Start 14-Day Trial

Building a production pipeline that pairs Amazon SNS with an external storage substrate requires disciplined schema design, validation, and error recovery.

Step 1: Establish the Notification Schema

Avoid sending raw text or ad-hoc JSON dictionaries. Use a standardized, versioned event envelope that tells subscribers exactly how to retrieve and verify the payload:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "eventId": "evt_98412bc7-4e12-48a9",
  "eventType": "dataset.analysis.completed",
  "eventTimestamp": "2026-10-09T14:30:00Z",
  "producer": "agent-financial-auditor",
  "claimCheck": {
    "workspaceId": "ws_finance_corp_prod",
    "fileId": "file_q3_consolidated_ledger.xlsx",
    "fileUri": "fastio://workspaces/ws_finance_corp_prod/files/file_q3_consolidated_ledger.xlsx",
    "byteSize": 14892014,
    "checksumSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
  },
  "summary": "Q3 consolidated balance sheet verified across 14 subsidiaries with zero reconciliation discrepancies."
}

This compact event envelope allows high-throughput broadcast across SNS topics while keeping message volume well within standard broker boundaries.

Step 2: Publishing the Notification from Compute Workers

In an event-driven worker running on AWS Lambda, AWS Fargate, or a dedicated container, write the completed file to the workspace or storage layer first, then publish the claim check:

import json
import boto3
from botocore.exceptions import ClientError

sns = boto3.client("sns", region_name="us-east-1")
TOPIC_ARN = "arn:aws:sns:us-east-1:123456789012:agent-artifact-events"

def notify_artifact_complete(workspace_id: str, file_id: str, file_size: int, sha256: str, summary: str):
    event = {
        "eventId": "evt_98412bc7",
        "eventType": "dataset.analysis.completed",
        "claimCheck": {
            "workspaceId": workspace_id,
            "fileId": file_id,
            "byteSize": file_size,
            "checksumSha256": sha256
        },
        "summary": summary
    }
    
    try:
        response = sns.publish(
            TopicArn=TOPIC_ARN,
            Message=json.dumps(event),
            MessageAttributes={
                "EventType": {
                    "DataType": "String",
                    "StringValue": "dataset.analysis.completed"
                }
            }
        )
        return response["MessageId"]
    except ClientError as err:
        if err.response["Error"]["Code"] == "InvalidParameter":
            raise RuntimeError("SNS message exceeded configured payload limit") from err
        raise

Step 3: Consumer Ingestion and Selective Retrieval

Downstream consumers subscribing through Amazon SQS or AWS Lambda process notifications without saturating their memory:

1. Parse Event Envelope: The consumer deserializes the SNS message body.
2. Filter by Event Type: Using SNS subscription filter policies or application logic, the consumer inspects the EventType attribute before initiating data retrieval.
3. Decide Retrieval Strategy:
   • Lightweight consumers (such as alerting bots or notification loggers) read only the summary field and terminate without downloading the file.
   • Deep analysis agents connect via MCP or REST to query specific sections of the file.
   • Batch workers stream the raw file using chunked HTTP requests, verifying the SHA-256 hash upon receipt.

Step 4: Redrive Policies and Poison Message Handling

Network timeouts and temporary storage outages can prevent consumers from resolving claim checks. Protect your pipeline with a multi-tier recovery policy:

• Configure SQS Dead-Letter Queues: Attach a DLQ to the subscribing SQS queue with maxReceiveCount set to 3. If a consumer fails to resolve a claim check three times, the message moves to the DLQ.
• Implement Idempotency: Producers must generate deterministic event IDs. Consumers store processed eventId keys in an ephemeral cache for 24 hours to prevent duplicate processing if SNS redelivers a notification.
• Handle Dangling References: If a consumer receives a claim check pointing to a file that does not exist in storage, log a structured warning and route the message to the dead-letter queue rather than retrying indefinitely.

Selecting the right architecture for notification pipelines depends on payload size, subscriber diversity, and required data intelligence.

Architectural Tradeoffs Across Methods

The following matrix compares standard approaches for handling large message payloads and files in Amazon SNS:

Choosing the Right Pattern for Your System

Evaluate your workload against the following criteria:

• Use Direct SNS (256 KB): Choose this default for microservice signaling, heartbeat monitors, status flags, and alerting pipelines where payloads consist strictly of JSON metadata within standard broker limits.
• Use Expanded SNS (1 MiB): Choose this when microservice payloads occasionally reach larger JSON volumes, your endpoints are strictly Amazon SQS or AWS Lambda, and you maintain fewer than 100 total subscriptions.
• Use S3 Claim Checks: Choose the S3 Extended Client Library when building internal data pipelines entirely within Java or Python microservices where files exceed 1 MiB and do not require interactive exploration or agent retrieval.
• Use Intelligent Workspaces: Choose Fast.io when multi-agent teams, AI assistants, and human colleagues must collaborate on rich files. This approach eliminates broker payload caps while equipping agents with semantic search, structured Metadata Views, and granular audit controls.