A submission payload that fits in one request body today stops fitting the day a sender adds more locations, more coverages, or more attached history. The request is rejected, the sender retries, and the same error comes back.
A larger limit is not always the fix. For large payloads, the cleaner move is often to send a file location and let the receiver fetch the file, instead of pushing every byte through the request body.
This article covers where size limits show up when you send data into Guidewire, the three ways to handle a payload that is too big, and the signals that tell you a file location is the right call.
Where does a request body hit its limit?
A request body hits its limit at the first component in the path that enforces a maximum size, such as an application server or a messaging system.
That component rejects the request. The sender sees an error, and nothing arrives.
The limit Guidewire documents
Guidewire's Cloud API documentation states that composite requests are subject to application server limits on request body size. A composite request can be too large to process even when its subrequest count is at or below the allowed maximum.
In the base configuration, that maximum is 100 subrequests and subselections combined. A single request therefore faces two limits: one on count and one on size.
Why messaging systems reject large messages
Messaging systems reject messages that exceed a configured maximum. Microsoft's Azure Architecture Center lists that rejection as the first constraint on sending payloads inline through a messaging system.
If your sender routes data through a queue or broker before it reaches Guidewire, that broker's limit applies to your payload too.
Why a larger limit does not settle it
The rejection is only the visible cost. The same guidance notes that large payloads consume disproportionate broker memory and disk compared to the routing data the broker needs, and that larger messages add serialization, transfer, and deserialization time to every operation.
Raising a limit moves the point of failure. It does not remove the load that every component in the path carries.
What are the three ways to send a payload that is too big?
Three options handle a payload that exceeds a request limit: shrink it and send it inline, split it into smaller requests, or send a pointer to a stored file.
We call this the Inline, Split, or Point test. Each option trades one cost for another, and the table shows where each cost lands.
Option | What the sender does | What it costs |
|---|---|---|
Inline | Compresses the payload or uses a compact serializer, then sends one request | Works only when the reduced payload fits the limit and both sides use the same format |
Split | Sends a sequence of smaller requests | Adds sequencing, correlation, duplicate handling, and reassembly |
Point | Stores the file and sends its location | Adds a storage dependency, a retrieval hop, and lifecycle ownership |
Inline with compression
Compression reduces repetitive text, and a compact serializer reduces message overhead. JSON payloads repeat field names across every location and coverage, which is exactly the repetition compression targets.
Choose this route when the reduced payload fits comfortably inside the limit and every producer and consumer can use the same format. If the payload still does not fit, move to one of the other two options.
Split and aggregate
Splitting divides one large payload into a sequence of smaller messages. It works when the receiver can process each piece independently or reassemble the pieces after delivery.
The data stays in the request path, but the work moves to the sender and the receiver. Both sides must handle ordering, matching pieces to the same submission, duplicates, and reassembly.
Point to a file location
This is the Claim Check pattern. The sender writes the full payload to an external data store and sends only a reference to it. The receiver uses the reference to retrieve the payload when it is ready to process it.
The request stays small, so size-limit rejection no longer applies to it. The cost is a second system that the receiver must reach.
When does a file location beat an API body?
A file location beats an API body when payloads regularly exceed the request limit, when large bodies strain the components carrying them, or when sensitive content should stay out of the request path.
The table sets each signal beside its opposite, so you can check your own payloads against both columns.
Signal | Choose a file location when | Choose an inline body when |
|---|---|---|
Payload size | Payloads regularly exceed the limit | Payloads stay within the limit |
Latency | An extra retrieval hop is acceptable | End-to-end speed is the top priority |
Routing | Several components serialize or decrypt the payload on the way | The payload crosses one hop |
Coordination | Sender and receiver agree on how a location is written and read | The two systems cannot coordinate |
Signals that favor a file location
Size is the first signal, and routing is the second. When a payload passes through several components that each serialize, deserialize, or decrypt it, a small location token removes that repeated work at every hop.
Sensitive content is the third. A secured store can apply dedicated access controls to the file, which keeps the content away from unrelated services such as queue-monitoring tools.
Signals that favor an inline body
Latency decides many cases. Each retrieval adds a network trip, so a workload that needs the lowest possible end-to-end time can lose more than it gains.
Fit decides the rest. If the payload stays within the limit and creates no throughput problem, an inline send is simpler and faster than adding a storage dependency.
Payloads that outgrow the limit
Submission payloads grow with locations, coverages, and loss history. Claim payloads grow with the documents and notes attached at first notice of loss.
Test the route with the largest submission you expect to send, not the typical one. A route that only works for small payloads fails at the worst moment.
What does a reliable file-location handoff need?
A reliable handoff writes the file first, confirms the write, and only then sends the location. The order matters because the file write and the location send happen in two separate systems and are not one atomic transaction.
The sequence has six steps:
The sender writes the full payload to a store that both sides can reach.
The sender confirms the write succeeded.
The sender sends the file location in the request instead of the payload.
The receiver reads the location and retrieves the file.
The receiver validates and processes the payload.
The designated owner deletes the file once it is no longer needed.
Order of operations
A failure after the file write but before the location send leaves an orphaned file. A location sent before the file is retrievable gives the receiver a reference it cannot resolve.
Send the location only after the write succeeds. That one rule prevents the second failure outright.
Retention and ownership
Name one owner for deleting the file. Coordinate message expiration with file retention so a valid location never points to deleted data.
The store must stay available and durable for as long as any receiver needs the file. An outage in the store stalls every payload that depends on it.
Integrity and duplicates
Retries can deliver the same location more than once, so the receiver must process duplicates safely. Processing the same submission twice is a data problem, not a network problem.
When the receiver needs proof that the file is the one the sender wrote, include a content hash or a digital signature with the location. Define in advance what happens on a mismatch, such as rejecting the file or routing it for investigation.
Access control
Do not embed security tokens in the location. Keep authorization as a separate interaction between each system and the store.
This keeps credentials out of the message that travels through the request path.
What stays the same whatever route the payload takes?
Moving the bytes is half the job. Whether the payload arrives inline, in pieces, or as a file, its fields still have to land in the right place in Guidewire.
Check the JSON before you send it
A syntax error found before the send costs a corrected file. The same error found after the send costs a failed request and a retry.
Validate the file for syntax before you store it, because a stored file with a syntax error fails at the receiver anyway.
Map each field to the structure Guidewire expects
Payload mapping matches each field in a sender's data to the field Guidewire expects, so a submission or claim lands in the right place on the first send.
A person who knows the source data should review that mapping. An unreviewed mapping moves wrong data as readily as it moves right data.
Keep a record of every request
Log each request, each response, and each error against the file location that triggered it. When a send fails, the record shows whether the file was missing, unreadable, or rejected at the receiver.
How InsOps Helps
InsOps builds an insurance-trained AI that assists with moving submission data into Guidewire. LiLa, our insurance-trained LLM, drafts the field mapping from your payload to the Guidewire structure, and a person on your team reviews and confirms every mapping before data moves.
The InsOps Integration Gateway gives MGAs, brokers, TPAs, and underwriting vendors a prebuilt route into Guidewire PolicyCenter and ClaimCenter. Senders register in a self-service portal, bring their payload, and configure it without building their own connector. Large payloads are sent as a file location instead of a request body.
The gateway runs inside your own environment, so PII and PHI stay in controlled infrastructure. InsOps is a Guidewire technology partner with prebuilt connectors to Guidewire's core products.
If you are evaluating how to exchange submission data with Guidewire without a custom connector build, contact us to talk through what this looks like for your operation.
Frequently Asked Questions
What is the Claim Check pattern?
The Claim Check pattern stores a large payload in an external data store and sends only a reference to it through the messaging system. The receiver presents that reference to retrieve the payload when it needs to process it.
Why do large API payloads get rejected?
Application servers and messaging systems enforce configured maximum sizes, and a request over the maximum is rejected. Guidewire's Cloud API documentation notes that composite requests are subject to application server limits on request body size.
How do you send a large payload into Guidewire?
Check the payload size against the limit first, and send inline if compression brings it under. If it still exceeds the limit and sender and receiver can coordinate, send a file location. Split the payload only when the receiver can process the pieces independently or reassemble them.
Is splitting a payload better than sending a file location?
Splitting keeps the data in the request path but adds sequencing, correlation, duplicate handling, and reassembly. A file location adds a storage dependency and a retrieval hop. Choose the burden your team handles more reliably.
What should you track to know a file-location handoff works?
Track rejected sends, locations that fail to resolve, duplicate deliveries, and files held past their retention date. A rising count in any of the four points to a specific fix in the handoff.
How does the InsOps Integration Gateway help?
The InsOps Integration Gateway sends large payloads into Guidewire as a file location, and LiLa drafts the field mapping from the sender's payload to the Guidewire structure. A person confirms every mapping before data moves.
What happens if the file is deleted before the receiver fetches it?
The location points to nothing, and processing stalls. Coordinating message expiration with file retention, and naming one owner for deletion, prevents it.