बड़ी PDF अपलोड के अस्वीकार होने पर: 100 MiB की अनुरोध-निकाय सीमा और वह त्रुटि जो ग़लत दिशा दिखाती है

जो बड़ी PDF अपलोड नहीं होती, वह आमतौर पर ख़राब फ़ाइल नहीं होती। अनुरोध-निकाय प्रति-अनुरोध सीमा से टकरा जाता है: 100 MiB, यानी 104,857,600 बाइट। यह पूरे निकाय पर नापा जाता है, multipart बाउंड्री और फ़ील्ड शीर्षलेखों सहित, और ठीक यही आँकड़ा पास होता है जबकि एक बाइट ज़्यादा अस्वीकार हो जाता है।

जो त्रुटि लौटती है, वह कहीं और इशारा करती है। ऑपरेशन एंडपॉइंट 400 लौटाते हैं, code को bad_request पर सेट करके, और विवरण कहता है कि कोई multipart फ़ील्ड पढ़ा नहीं जा सका, जिसमें आकार का कहीं ज़िक्र नहीं होता। जो क्लाइंट code पर शाखा बनाता है, वह इसे पैरामीटर त्रुटि दर्ज करता है और फ़ील्ड नाम जाँचने चल देता है, जबकि बदलने वाली चीज़ फ़ाइल का आकार है।

वही 100 MiB उलटी दिशा पर भी लागू होता है। Idempotency-Key ले जाने वाला अनुरोध कैश करने से पहले प्रतिक्रिया को मेमोरी में पढ़ता है, उसी आँकड़े के मुक़ाबले, और उससे ऊपर जाने पर कॉलर को 500 मिलता है जबकि ऑपरेशन पहले ही पूरा हो चुका होता है। एक आँकड़ा, दो उलटे विफलता-प्रकार।

                     100 MiB = 104,857,600 बाइट (यही आँकड़ा पास होता है)
                                   |
                +------------------+------------------+
                |                                     |
         अंदर आना (अनुरोध-निकाय)             बाहर जाना (प्रतिक्रिया-निकाय)
   पूरा निकाय, multipart बाउंड्री          केवल Idempotency-Key के साथ,
   और फ़ील्ड शीर्षलेख सहित; एक             कैश मिस और अपस्ट्रीम 2xx
   ऑपरेशन और पाइपलाइन इसे साझा करते हैं
   ऊपर: 400 + bad_request                  ऊपर: 500, कुछ भी कैश नहीं
   (विवरण: एक multipart फ़ील्ड पढ़ा नहीं जा सका)

आरेख टिप्पणी: एक ही सीमा, और उसके अंदर-आने तथा बाहर-जाने वाले पक्ष अलग-अलग स्थिति कोड और उलटे परिणाम लौटाते हैं।

यह सीमा बाउंड्री सहित पूरे अनुरोध-निकाय को गिनती है

100 MiB एक अनुरोध के निकाय को सीमित करता है, न कि एक फ़ाइल के आकार को और न ही डिकंप्रेशन के बाद के आकार को।

• एक ऑपरेशन और बहु-चरणीय पाइपलाइन यह आँकड़ा साझा करते हैं। एक ही /api/v1/pipeline कॉल में काम को 10 चरणों में बाँटने से छत 1 GB नहीं हो जाती; चरणों की संख्या सिर्फ़ चलने का समय प्रभावित करती है।
• बाउंड्री का आँकड़ा ख़ुद पास होता है: 104,857,600 बाइट का अनुरोध-निकाय निकल जाता है, 104,857,601 बाइट नहीं।
• निकाय में फ़ाइल बाइट्स के साथ-साथ हर फ़ील्ड के शीर्षलेख और बाउंड्री डिलिमिटर भी होते हैं, इसलिए एक फ़ाइल के लिए बची छूट 100 MiB से सख़्ती से कम होती है। ठीक 104,857,600 बाइट की फ़ाइल अस्वीकार हो जाती है।

यही आख़िरी बात अमल में सबसे आसानी से चूक जाती है: curl -F बाउंड्री ख़ुद जोड़ देता है, इसलिए फ़ाइल के आकार को उस रेखा से मिलाना कभी सही नहीं बैठेगा।

सीमा से ऊपर 400 और bad_request मिलता है

सीमा से ऊपर की प्रतिक्रिया 413 का इस्तेमाल नहीं करती, और उसमें आकार के बारे में कोई शब्द नहीं होता। एक बाइट ज़्यादा के निकाय से इसे दोहराइए:

head -c 104857601 /dev/zero > /tmp/over.bin
curl -s -X POST "$API_BASE/api/v1/misc/compress-pdf" \
  -H "X-API-KEY: $API_KEY" \
  -F "fileInput=@/tmp/over.bin"

HTTP/1.1 400 Bad Request
content-type: application/problem+json

{ "code": "bad_request",
  "detail": "failed to read multipart field: Error parsing `multipart/form-data` request",
  "hint": "Fix request parameters or upload a valid PDF.",
  "status": 400,
  "title": "Bad Request",
  "type": "https://pdf123.xyz/developers/errors#bad_request" }

तीन बातें एक साथ पढ़ें:

• स्थिति 400 है। निकाय पढ़ने की विफलता यहाँ bad_request के रूप में वर्गीकृत होती है और फिर भी problem+json से गुज़रती है, इसलिए "सीमा से ऊपर का मतलब 413" के लिए लिखा क्लाइंट ग़लत शाखा पकड़ता है।
• code bad_request है, जो त्रुटि कोड तालिका में मौजूद असली प्रविष्टि है। यह किसी कैच-ऑल में नहीं गिरता; यह ग़लत टाइप किए फ़ील्ड नाम या टूटी multipart एन्कोडिंग के साथ एक ही कोड साझा करता है, और उस तालिका में कुछ भी आकार से संबंधित नहीं है।
• hint कहता है कि मान्य PDF अपलोड करें। आपकी अपलोड की गई फ़ाइल बहुत संभवतः एक मान्य PDF है जो संयोग से कुछ सौ बाइट ज़्यादा बड़ी है।

तो पहचान स्थिति कोड नहीं, निकाय का बाइट-संख्या है: जिस 400 के detail में failed to read multipart field हो, वहाँ फ़ॉर्म दोबारा खँगालने के बजाय अगला क़दम आकार नापना है।

413 इस साइट पर होता भी है, बस ऑपरेशन एंडपॉइंट पर नहीं। फ़ाइल अपलोड लेने वाला हर प्रवेश-बिंदु 100 MiB तक उठाया गया है, जबकि अपलोड न लेने वाले एंडपॉइंट अब भी HTTP फ़्रेमवर्क (Rust के axum) के 2 MiB डिफ़ॉल्ट पर चलते हैं, जहाँ सीमा से ऊपर का निकाय 413 और सादे टेक्स्ट की एक पंक्ति पाता है:

head -c 2097153 /dev/zero > /tmp/big.json
curl -s -w '\n%{http_code}\n' -X POST "$API_BASE/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  --data-binary @/tmp/big.json

Failed to buffer the request body: length limit exceeded
413

एक ही तथ्य, एंडपॉइंट के अनुसार दो स्थिति कोड और दो प्रतिक्रिया-निकाय। किसी एक का अनुभव दूसरे पर ले जाने से आप ग़लत रास्ते पर जाएँगे।

वापसी दिशा पर उसी आँकड़े वाली दूसरी विफलता

Idempotency-Key वाला अनुरोध अपनी प्रतिक्रिया कैश करता है ताकि पुनः प्रयास उसे दोबारा चला सके। कैश करने का मतलब है प्रतिक्रिया-निकाय को पहले मेमोरी में पढ़ना, और वह पढ़ाई उसी 100 MiB से सीमित है, हालाँकि इसके लिए शर्तें बहुत संकरी हैं:

1. अनुरोध Idempotency-Key लेकर आया
2. कैश मिस हुआ, यानी यह कुंजी नई है
3. अपस्ट्रीम ऑपरेशन ने 2xx लौटाया

विफल प्रतिक्रियाएँ कैश नहीं होतीं और सीधे निकल जाती हैं, इसलिए इस सीमा तक सिर्फ़ कामयाब बड़ा आउटपुट पहुँचता है।

वहाँ जो होता है, वही याद रखने लायक बात है: आपको 500 मिलता है, और कैश में कुछ भी नहीं लिखा जाता। ऑपरेशन चल चुका होता है, फिर भी कॉलर को विफलता दिखती है; और चूँकि कुछ भी कैश नहीं हुआ, पुनः प्रयास पूरी चीज़ दोबारा चलाता है। इडेम्पोटेंसी कुंजी डुप्लिकेट काम हटाने के लिए होती है और ठीक तब विफल होती है जब उसकी सबसे ज़्यादा ज़रूरत हो, किसी पूरे हो चुके काम को सर्वर की ख़राबी बना देती है। यह कैश प्रक्रिया की मेमोरी में रहता है और कभी डिस्क पर नहीं लिखा जाता, इसलिए पुनःआरंभ उसे मिटा देता है; इसके अर्थ के लिए देखें Idempotency-Key: PDF कार्यों के लिए सुरक्षित पुनः प्रयास।

100 MiB कोई कॉन्फ़िगर करने योग्य प्लेटफ़ॉर्म सेटिंग नहीं है

यह आँकड़ा बदला नहीं जा सकता। कोई एनवायरनमेंट वेरिएबल इसे किसी भी दिशा में न बढ़ाता है न घटाता है; कोई और संख्या चाहिए तो कोड बदलकर इमेज दोबारा बनानी पड़ेगी। इसे तैनाती सेटिंग की तरह ढूँढ़ेंगे तो नहीं मिलेगा।

यह सिर्फ़ एक कोटा भी नहीं है। अनुरोध-निकाय के बाइट्स प्रसंस्करण से पहले पूरे मेमोरी में पढ़े जाते हैं, इसलिए हर समवर्ती बड़ा अपलोड अपने साथ उतनी ही मात्रा रखता है। छत उठाने का मतलब है उसके साथ ऊँची मेमोरी-चोटी स्वीकार करना: यही संख्या एक अकेले अनुरोध को पूरी प्रक्रिया नीचे खींच ले जाने से भी रोकती है।

डिफ़ॉल्ट स्व-होस्ट की गई तैनाती में कोई रिवर्स प्रॉक्सी नहीं होता, और पोर्टल सबमिट करने से पहले आकार नहीं जाँचता, इसलिए वह अस्वीकृति सर्वर की अपनी सीमा से आती है। सामने nginx लगाइए तो पहले nginx से टकराएँगे: client_max_body_size डिफ़ॉल्ट रूप से सिर्फ़ 1 MiB की अनुमति देता है और 413 लौटाता है, जो ऊपर की तुलना जैसा ही आकार है और उसे वही सीमा समझ लेना आसान है।

टकराने पर क्या करें

सबसे सस्ते से शुरू:

1. भेजने से पहले नापें। अनुरोध न जाने से पहले निकाय की बाइट-संख्या की तुलना 104,857,600 से करें, और बाउंड्री के लिए जगह छोड़ें। यह बाद में स्थिति कोड पढ़ने से बेहतर है।
2. फ़ाइल को सीमा के भीतर संपीड़ित करें। स्कैन का आकार ज़्यादातर उसकी इमेज परत से आता है, और दोबारा संपीड़न आमतौर पर उसका दिखने लायक हिस्सा हटा देता है। PDF संपीड़ित करें ब्राउज़र में चलता है, स्क्रिप्ट की ज़रूरत नहीं।
3. काम को कई कॉल में बाँटें। जहाँ सामग्री बँट सके, PDF बाँटें और कुछ अनुरोधों में भेजें: छत उठाने से कम झंझट, और यह एक अनुरोध की मेमोरी को ऊपर नहीं धकेलता।
4. सीमा सिर्फ़ तब बदलें जब एक ही अनुरोध में भेजने की सख़्त ज़रूरत हो। उसका मतलब है कोड बदलना और दोबारा बनाना, साथ ही पिछले हिस्से की मेमोरी क़ीमत स्वीकार करना।

यह सीमा क्लाइंट से पहले ही फ़ैसला माँगती है

दोनों विफलताएँ एक ही नतीजे पर इशारा करती हैं: 100 MiB का आँकड़ा भेजने से पहले क्लाइंट को ख़ुद निकालना होगा। अंदर की दिशा में आपको bad_request मिलता है, ऐसा कोड जो आकार के बारे में कुछ नहीं कहता; बाहर की दिशा में 500, जो सर्वर की ख़राबी जैसा दिखता है। अनुरोध निकलने से पहले बाइट गिनना ही आँकने का वह तरीक़ा है जो इस पर निर्भर नहीं कि त्रुटि-संदेश क्या कहता है।