A Guide to Avoiding Pitfalls with Content-Length in HTTP Requests

Scenario Recreation: A Frustrating JSON Parsing Issue

Recently, during a project integration process, our team encountered a bizarre JSON parsing issue. Here’s what happened:

The frontend team copied a normal cURL request from Chrome Developer Tools:

curl -X POST https://api.ourcompany.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "Content-Length: 187" \
  -d '{"order_id":"123456","products":[{"sku":"A001","qty":2}],"remark":"Weekend Delivery"}'

This request worked perfectly, but when the backend team tried to modify the product quantity:

# Only changing the quantity from 2 to 1
curl -X POST https://api.ourcompany.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "Content-Length: 187" \
  -d '{"order_id":"123456","products":[{"sku":"A001","qty":1}],"remark":"Weekend Delivery"}'

The interface suddenly reported an error, returning a strange JSON parsing exception:

message": "JSON parse error: Unexpected end-of-input...

What’s even stranger is that as long as the request data remains unchanged, it works fine; any modification leads to an error. What could be the reason?

Troubleshooting: It’s All About Content-Length

What is Content-Length?

In simple terms, Content-Length tells the server: “I am sending you XX bytes of data in this request.” It is a header field in the HTTP protocol that indicates the size of the request body.

Where is the problem?

Upon careful comparison, we found that the issue lies in the hardcoded <span>Content-Length: 187</span>. This number was calculated by the frontend when copying the request based on the original data. However:

1. The original request body was exactly 187 bytes
2. The modified request body might become 185 bytes (because the number changed from 2 to 1)
3. But Content-Length remains 187

This is akin to:

• You tell the courier there are 3 packages (Content-Length=3)
• But you actually only give 2
• The courier will keep waiting for the 3rd package, ultimately timing out

Two Types of Errors

1. Content-Length > Actual Length:

• The server will wait for the remaining data
• Eventually timing out or throwing an error

Content-Length < Actual Length:

• The server will truncate the data
• Leading to incomplete JSON

Why Does This Happen?

Traps of the Tools

When using Chrome Developer Tools to “Copy as cURL”, it hardcodes the Content-Length at that moment. This can cause issues in the following situations:

• Modifying request parameters
• Adjusting spaces or line breaks
• Data desensitization

Who Should Set It?

In general:

• Automatic Setting: Tools like cURL, Postman, etc., will calculate it automatically
• Manual Setting: Not recommended! Unless you are very clear about what you are doing

Solution: One Simple Trick

The solution is actually very simple: When copying cURL, just delete the Content-Length line!

Let the tool calculate the length automatically, which is both convenient and safe.

Experience Summary

1. Golden Rule: Never manually set Content-Length
2. Debugging Tip: When encountering JSON parsing failures, first check if the lengths match

This experience teaches us that every detail in the HTTP protocol is crucial. A small Content-Length can cause developers to struggle for half a day. Therefore, pay attention to these details in daily development and accumulate experience to avoid unnecessary troubles.