Your timeout issue requires implementing the chunked upload pattern. Here’s the complete solution addressing all aspects:
Multipart Upload Implementation: Use the three-phase chunked upload API instead of single POST. First, initiate an upload session:
POST /crmRestApi/resources/11.13.18.05/contracts/{id}/attachments/initiate
{"fileName":"contract.pdf","fileSize":35000000,"chunkSize":5242880}
Response: {"uploadSessionId":"SESSION-123","totalChunks":7}
This creates a server-side session and calculates chunk count. Use 5MB chunks (5242880 bytes) to stay safely under the 25MB gateway limit.
File Size Limits: The 50MB documentation refers to total file size, not request size. The API gateway enforces a 25MB per-request limit which is why your single upload fails. By chunking to 5MB pieces, you can upload files up to 100MB if needed. Don’t increase the gateway limit - it’s set at 25MB for security and performance reasons. Chunked upload is the intended pattern for large files.
API Gateway Configuration: The timeout is enforced at multiple layers. The API gateway has a 60-second request timeout that cannot be overridden via client settings. This protects backend services from long-running requests. Chunked upload solves this because each individual chunk request completes in 5-10 seconds. The total upload might take several minutes, but no single request exceeds the timeout.
Chunked Transfer Process: After initiating, upload chunks sequentially:
POST /crmRestApi/resources/11.13.18.05/attachments/upload
Headers: Upload-Session-Id: SESSION-123, Chunk-Number: 1
Content-Type: application/octet-stream
Body: [5MB binary chunk]
Repeat for each chunk, incrementing Chunk-Number. The API validates chunk order and size. Finally, finalize the upload:
POST /crmRestApi/resources/11.13.18.05/attachments/finalize
{"uploadSessionId":"SESSION-123"}
This triggers server-side reassembly and creates the final attachment record.
Error Handling and Retry Logic: Implement robust error handling for each phase. If chunk upload fails, retry that specific chunk up to 3 times with exponential backoff. If initiation or finalization fails, restart the entire upload. Store the upload session ID and track completed chunks so you can resume interrupted uploads. The session remains valid for 24 hours.
Performance Optimization: Upload chunks sequentially rather than parallel to avoid overwhelming the API gateway. However, you can optimize by preparing the next chunk while the current one uploads. Use streaming to avoid loading the entire file into memory - read and upload 5MB at a time. For very large contracts, consider background processing with status updates to the user rather than blocking their workflow.
Implementation tip: Create a reusable upload service class that handles chunking logic, retry mechanism, and progress tracking. This makes it easy to use chunked upload throughout your application wherever large file uploads are needed.
This draft is based on general Oracle CX Cloud knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.