Guest API - File Uploads Failing Intermittently - 400 Bad Request - 'fileSize'

Hey everyone!

I’m hoping someone can point me in the right direction here. We’re building a custom chat widget using the WebSocket Guest API - specifically, we’re trying to get file uploads working reliably! We’ve got around 800 agents, and this is becoming a real pain point.

Everything seems set up correctly, but we’re seeing intermittent failures when users attempt to upload files larger than about 2MB. The API is responding with a 400 Bad Request, and the error message in the console is pretty unhelpful: "{\"error\":\"Invalid request\",\"message\":\"fileSize\"}". It’s just… fileSize?

We’re using the sendMessage method with the attachment parameter, and we’ve verified that the file data is being correctly serialized and sent as a base64 encoded string. We’re on Genesys Cloud v38.0.0 and using the latest Guest API SDK (v3.1.2). The Architect flow has a simple “Send Web Chat Message” node, nothing custom there.

The interesting thing is, smaller files (under 2MB) upload perfectly every time! It feels like there’s a size limit being enforced somewhere, but we can’t find any documentation specifying a hard limit on file sizes for the Guest API. We’ve checked our tenant’s file upload limits in Admin - those are set to 25MB.

Here’s a snippet of the code we’re using:

const payload = {
 text: 'Here’s my file!',
 attachment: {
 filename: 'report.pdf',
 contentType: 'application/pdf',
 content: base64File
 }
};

chat.sendMessage(payload)
 .then(response => console.log('Message sent!', response))
 .catch(error => console.error('Error sending message', error));

We’ve been poking around in the network tab, and it looks like the entire payload is being sent - it isn’t getting truncated before the error. It’s just the API seemingly rejecting the request. The errors aren’t consistent either, sometimes it’s immediate, other times it takes a few seconds.

Is there a size limit that’s not documented? Or could this be a server-side issue? We’ve tried different file types (PDF, JPG, DOCX) and it doesn’t seem to be file-type specific. It’s just large files, and it’s happening randomly. It’s really frustrating!

Any thoughts?

Thanks!

Seeing 400s on file uploads with the Guest API isn’t unusual. It’s almost always the file size or the content type. We’re on Genesys Cloud, and hitting those limits is easy when you’ve got a lot of users.

Here’s what’s usually happening. Genesys Cloud’s Guest API has strict limits. You’ll find them in the documentation (ugh, I know) but generally it’s around 10MB max file size. Also, they’re picky about content types - only certain ones are allowed.

Here’s a quick repro/fix.

1. Validate client-side: Before you even try to send the file, check the size in JavaScript. Something like this:

function checkFileSize(file) {
 const maxSizeInMB = 10;
 const maxSizeInBytes = maxSizeInMB * 1024 * 1024;
 if (file.size > maxSizeInBytes) {
 alert("File size too large. Max 10MB");
 return false;
 }
 return true;
}

2. Content type check: Same deal - make sure the content type is in Genesys Cloud’s approved list. You can get that list in the docs.
3. Data Action pre-check: Wrap the API call in a Data Action. This lets you add some extra logging/error handling and, crucially, check the size/type again before it hits the Genesys Cloud API. Investigate using a Data Action to inspect the attachment.contentType and attachment.content.length before sending the message.

We’ve seen cases where the front-end validation fails. Adding a Data Action check is a good safety net. It’s a bit of overhead, but avoids those intermittent 400s in prod.

Anyone seen this?

maybe is the content type? we’re on Genesys Cloud, and i think NICE and Talkdesk have similar problems with this. try to add Content-Type: application/octet-stream in the header - sorry for newbie question, i am still learning the API, and getting some strange errors.

hey! yeah the content type thing is super common, we see it all the time. The suggestion above is right about the limits - 10MB is the hard stop on Genesys Cloud for the Guest API file uploads, and it’s brutal when folks try to send bigger stuff.

Content-Type: application/octet-stream is a good start, like As noted above, but sometimes that doesn’t quite cut it. I ran into something similar a few months back - the API was still rejecting perfectly valid PDFs, even with that header. Turns out, the API is doing a check on the actual file header - not just the content type you send.

So, what worked for us was forcing the correct MIME type in the file itself, before sending. It’s a bit of a hacky workaround, but it fixed it. For example, if you’re dealing with a PDF, make sure the PDF’s internal header correctly identifies it as a PDF. Some tools will let you reset this.

Also, check the file permissions. If the process creating the file doesn’t have read permissions, the API will choke on it, and you’ll get a 400. Sounds dumb, but it happened.

Honestly, the Guest API docs aren’t the greatest - they’ll tell you what the limits are, but not why you’re hitting them. It took a lot of testing to figure out the header issue.

Hi all,
We’re on Genesys Cloud, and it sounds like you’re running into the FILE_SIZE restriction on the GUEST_API. Are you checking the file size on the client side BEFORE the upload starts? It’s easy to miss that step - we’ve seen it before. The WEM routing engine won’t tell you much beyond the 400 error, so client-side validation is important.

The documentation says 10MB is the MAX_FILE_SIZE, but the API sometimes rejects files even below that limit. Try this - BEFORE you send the file, wrap the payload in a PRE_CHECK routine. IF (FILE_SIZE > 8MB) THEN REJECT (FILE) ELSE SEND (FILE). That gives you some buffer. Also, double-check the CONTENT_TYPE mapping - sometimes the API is sensitive to capitalization.