Status code আর error format — problem details আর idempotency

১ · Status code একটি সিদ্ধান্ত, অভ্যাস নয়

কুরিয়ারের অফিসে পার্সেল দিলে আপনি একটি রসিদ পান। রসিদে লেখা থাকে “গৃহীত”, “ঠিকানা ভুল”, “প্রাপক নেই” বা “আজ গাড়ি যায়নি”। প্রতিটি লেখার পরের কাজ আলাদা। ঠিকানা ভুল হলে আবার পাঠিয়ে লাভ নেই, ঠিকানা বদলাতে হবে। গাড়ি না গেলে কাল আবার খোঁজ নিলেই হয়। HTTP-র status code ঠিক এই রসিদ। সে শুধু খবর দেয় না, পরের কাজও ঠিক করে দেয়।

আগের পর্বগুলোয় আপনি server-এর ভেতরটা দেখেছেন। পর্ব ২৭-এ ইনপুট যাচাই আর পর্ব ২৮-এ central error handler বানানো হয়েছে। সেই কোড আর লিখব না। এখানে প্রশ্নটি অন্য: API-র বাইরে বসে থাকা client কী দেখে, আর সেটি দেখে কী করবে? এই পর্বটি client-এর চোখে API নকশা। URL আর method-এর নকশা আছে পর্ব ৩২-এ (REST resource নকশা)।

Status code কে কে পড়ে? শুধু আপনার React কোড নয়। Browser 301 আর 304 দেখে নিজেই কাজ করে। CDN code দেখে ঠিক করে কী জমাবে। পর্ব ১৯-এর TanStack Query code দেখে retry করে। Monitoring 5xx গুনে alert বাজায়। তাই ভুল উত্তরে 200 আর body-তে {"success":false} দিলে এরা সবাই ধরে নেয় সব ঠিক আছে। মাঝের cache সেই ভুলটিই জমিয়ে সবাইকে দিতে পারে।

আরেকটি পরিবার আছে, 1xx. যেমন 101 দিয়ে WebSocket-এ সংযোগ বদলায় (পর্ব ৬০). সাধারণ API নকশায় এগুলো আপনাকে বেছে নিতে হয় না। আর client কোনো অচেনা code পেলে তার শ্রেণি ধরে নেয়: অচেনা 4xx মানে 400-এর মতো, অচেনা 5xx মানে 500-এর মতো। RFC 9110 এটাই বলে। তাই খুব নির্দিষ্ট code নিয়ে দুশ্চিন্তার চেয়ে সঠিক পরিবার বেছে নেওয়া বেশি জরুরি।

২ · কাজ হয়েছে: 200, 201, 202, 204, 301 আর 304

সফল উত্তরেও সিদ্ধান্ত আছে। সব জায়গায় 200 দিলে কোড চলে, কিন্তু client কম তথ্য পায়। বাজারঘরের API-র সত্যিকারের উত্তরগুলো পাশাপাশি দেখুন।

নিচের সব পেস্ট করা উত্তরে Date, Content-Length ধরনের লাইন আর লম্বা id ছোট করা হয়েছে, বাকিটা সত্যিকারের run. Location আর Retry-After লক্ষ করুন।

$ curl -si -X POST -H 'content-type: application/json' -H 'Authorization: Bearer token-rafi' \
    -d '{"sku":"RICE-5KG","qty":1}' http://127.0.0.1:47333/v1/orders
HTTP/1.1 201 Created
Location: /orders/1
Content-Type: application/json; charset=utf-8

{"id":1,"total":700}

$ curl -si -X POST -H 'Authorization: Bearer token-rafi' http://127.0.0.1:47333/reports
HTTP/1.1 202 Accepted
Location: /jobs/71
Retry-After: 5

{"jobId":71,"state":"queued"}

$ curl -si -X DELETE -H 'Authorization: Bearer token-rafi' http://127.0.0.1:47333/cart/items/5
HTTP/1.1 204 No Content

$ curl -si -X DELETE -H 'Authorization: Bearer token-rafi' http://127.0.0.1:47333/cart/items/5
HTTP/1.1 404 Not Found

$ curl -si http://127.0.0.1:47333/old-products/1
HTTP/1.1 301 Moved Permanently
Location: /products/1

দুটি জিনিস ভাবার মতো। প্রথমত, দুবার DELETE করলে প্রথমে 204, পরে 404 এলো। তবু DELETE idempotent, কারণ idempotent কথাটি server-এর অবস্থা নিয়ে, উত্তর নিয়ে নয়। দুবার পরেও পণ্যটি কার্টে নেই। দ্বিতীয়ত, 202 একটি সৎ উত্তর: “নিয়েছি, হবে কি না এখনো জানি না”। লম্বা report বা ইমেইলের মতো কাজে দরকার, যার পুরো রূপ পর্ব ৬২-তে।

৩ · ভুল অনুরোধ: 4xx-এর জোড়াগুলো

4xx-এর সব কষ্ট কয়েকটি জোড়ায়। একবার ধরতে পারলে ইন্টারভিউয়ের অর্ধেক প্রশ্ন শেষ।

400 আর 422: পড়া গেল কি না

দর্জিকে একটি কাগজ দিলেন। হাতের লেখা পড়াই গেল না, এটি 400. পড়া গেল, কিন্তু লেখা “হাতা ৯৯ ইঞ্চি”, এটি 422. এই কোর্সে 400 মানে অনুরোধটি পড়া বা বোঝাই যায়নি, 422 মানে পড়া গেছে কিন্তু নিয়ম ভেঙেছে। পর্ব ২৭-এ এই ভাগ দেখেছেন। মনে রাখবেন, অনেক API সব ইনপুটের ভুলে 400 দেয়, আর সেটিও চলে। ধারাবাহিকতাই আসল। Idempotency-Key না পাঠালে আমরা 400 দিচ্ছি, কারণ IETF-এর খসড়াও তাই বলে।

401 আর 403: কে আপনি, আর আপনার কি অনুমতি আছে

অফিসের গেটে পরিচয়পত্র নেই, এটি 401. পরিচয়পত্র আছে, কিন্তু সার্ভার-রুমে ঢোকার অনুমতি নেই, এটি 403. প্রথমটি authentication, দ্বিতীয়টি authorization. 401-এর নাম “Unauthorized” হলেও অর্থ “পরিচয় পাইনি”, এই বিভ্রান্তি পুরোনো। RFC 9110 বলে 401-এ WWW-Authenticate header পাঠাতেই হবে। Client-এর আচরণও আলাদা: 401-এ login পাতায় নেওয়া বা token নবায়ন, 403-এ “অনুমতি নেই” দেখানো। 403-তে login পাতায় পাঠালে ব্যবহারকারী চক্রে পড়েন।

$ curl -si http://127.0.0.1:47333/orders/1
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="bazarghar"
Content-Type: application/problem+json; charset=utf-8

{"type":"https://bazarghar.example/problems/not-authenticated","title":"লগইন করা নেই","status":401,…}

404 আর 410, আর অস্তিত্ব লুকানো

404 মানে “এখানে এখন কিছু পাচ্ছি না”; পরে আসতেও পারে। 410 Gone মানে “ছিল, চিরতরে গেছে”, যেমন বন্ধ হওয়া কুপন EID2025. বেশিরভাগ API-তে 404-ই যথেষ্ট; 410 দিন যখন client-কে সত্যিই বলতে চান আর খোঁজ করবেন না।

আসল সূক্ষ্মতা অন্য জায়গায়। মিনা রাফির order চাইলে কী বলবেন? 403 দিলে মিনা জেনে গেলেন এই id-র order আছে। /orders/1, /orders/2 করে ঘুরলে কোনটি আছে আর দিনে কত order হয়, দুটিই বেরিয়ে আসে। তাই অন্যের জিনিস আর না-থাকা জিনিস, দুটিতেই হুবহু একই 404. RFC 9110-ও এই ব্যবহার মেনে নেয়। সত্যিকারের run:

# মিনা রাফির order চাইলেন
HTTP/1.1 404 Not Found
{"type":"…/order-not-found","title":"এই অর্ডারটি পাওয়া যায়নি","status":404,"instance":"urn:uuid:c12f88b2-…","code":"ORDER_NOT_FOUND",…}

# মিনা এমন order চাইলেন, যা নেই
HTTP/1.1 404 Not Found
{"type":"…/order-not-found","title":"এই অর্ডারটি পাওয়া যায়নি","status":404,"instance":"urn:uuid:c53b12a1-…","code":"ORDER_NOT_FOUND",…}

পার্থক্য শুধু এলোমেলো traceId-তে। কোডে এটি এক লাইনের কাজ: WHERE id = ? AND user_id = ?. তাই “আছে কি না” আর “কার” আলাদা করে দেখার সুযোগই থাকে না। 403 কখন? যখন জিনিসটির অস্তিত্ব গোপন নয়, যেমন একজন ক্রেতা পণ্যের দাম বদলাতে চাইলে; পণ্য তো সবার সামনেই। এই ঝুঁকির তত্ত্ব আছে broken access control পর্বে, আর কোড পর্ব ৪৮-এ।

বাকিগুলো এক টেবিলে

এখানে Express-এর একটি ফাঁদ আছে। Express নিজে 405 দেয় না। অসমর্থিত method-এ সে ধরে নেয় route মেলেনি, তাই 404. সত্যিকারের run:

$ curl -si -X DELETE http://127.0.0.1:47333/plain      # শুধু app.get('/plain') আছে
HTTP/1.1 404 Not Found

$ curl -si -X DELETE http://127.0.0.1:47333/products/1 # .all() বসানো আছে
HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD, PATCH

দ্বিতীয় ফলটি পেতে একই route-এর শেষে একটি .all() বসাতে হয়:

const methodNotAllowed = (allow) => (req, res) => {
  res.set('Allow', allow);
  throw new Problem(405, 'METHOD_NOT_ALLOWED');
};

app.route('/products/:id')
  .get(readProduct)
  .patch(auth, onlyAdmin, needJson, json, updateProduct)
  .all(methodNotAllowed('GET, HEAD, PATCH'));

এখন সিদ্ধান্তের ক্রমটি দেখুন। Code বাছাই আসলে ওপর থেকে নিচে একটি মই, আর প্রথম যে ধাপে আটকায় সেখানেই উত্তর। ক্রম বদলালে উত্তরও বদলায়, আর তথ্যও ফাঁস হতে পারে। যেমন অনুমতির আগে যাচাই করলে অননুমোদিত মানুষও আপনার schema জেনে যান। নিচের আটটি অনুরোধের ফল সত্যিকারের run থেকে নেওয়া।

1method ok?   else 4052who are you? else 4013allowed?     else 4034readable?    else 4005rules ok?    else 4226condition?   else 4127state ok?    else 4098all passed:  201

মইয়ের ওপরের দিকে 429 বা 413-ও বসে, কারণ এগুলো খরচের কাজ শুরু হওয়ার আগেই থামানো ভালো। ঠিক কোথায় বসবে, তা নির্ভর করে middleware-এর ক্রমের ওপর (পর্ব ২৬).

৪ · আমাদের সমস্যা: 500, 502, 503 আর 504

রেস্তোরাঁয় চারটি আলাদা দৃশ্য ভাবুন। রান্নাঘরে হাঁড়ি উল্টে গেল, এটি 500. ওয়েটার রান্নাঘর থেকে এমন কিছু আনলেন যা খাবারই নয়, এটি 502. আজ ভিড়ে বা মেরামতে দোকান সাময়িক বন্ধ, এটি 503. রান্নাঘর সময়মতো কিছুই দিল না, এটি 504. চারটিতেই খদ্দের খাবার পাননি, কিন্তু পরের কাজ আলাদা।

Lab-এ একটি ছোট নকল পেমেন্ট সার্ভিস চালিয়ে 502 আর 504 ঘটানো হলো। সে একবার ভাঙা HTML দিল, আরেকবার দেরি করল।

$ curl -si 'http://127.0.0.1:47333/boom'
HTTP/1.1 500 Internal Server Error
{"type":"…/internal","title":"আমাদের দিকে একটি সমস্যা হয়েছে","status":500,…,"code":"INTERNAL","traceId":"eab57c2c-…"}

$ curl -si 'http://127.0.0.1:47333/pay/check?mode=garbage'
HTTP/1.1 502 Bad Gateway
{"type":"…/upstream-bad-response","title":"পেমেন্ট সার্ভিসের উত্তর বোঝা গেল না","status":502,…}

$ curl -si 'http://127.0.0.1:47333/pay/check?mode=slow'
HTTP/1.1 504 Gateway Timeout
Retry-After: 5
{"type":"…/upstream-timeout","title":"পেমেন্ট সার্ভিস সময়মতো সাড়া দেয়নি","status":504,…}

সূক্ষ্ম পার্থক্য: 502 আর 504 আপনি সবসময় নিজে লেখেন না। বেশিরভাগ সময় এগুলো আপনার app-এর সামনে বসা proxy বা load balancer পাঠায়, আর তখন উত্তরটি আপনার JSON নয়, proxy-র HTML পাতা। তাই client-এর কোড ধরে নেবে না যে 5xx-এর body সবসময় JSON. প্রথমে Content-Type দেখবে। Downstream সংযোগ না পেলে কেউ 502, কেউ 503 দেন, এখানে দুই মতই চালু; পর্ব ২৮-এ আমরা 503 নিয়েছি।

৫ · Error format একটি চুক্তি: RFC 9457

Status code মোটা দাগের খবর। 409 বললে client জানে সংঘাত হয়েছে, কিন্তু কোন সংঘাত? মজুত শেষ, না SKU আগেই আছে? Frontend দুই ক্ষেত্রে দুটি আলাদা পর্দা দেখাবে। তাই body-তে আরও তথ্য লাগে, আর সেই আকার একবার প্রকাশ হলে সেটি চুক্তি। বদলালে অন্যের কোড ভাঙে। পর্ব ৩৫-এ এই চুক্তি OpenAPI-তে লেখা হবে।

একটি ভালো error-এর চারটি অংশ, আর প্রতিটির পাঠক আলাদা:

মানটি পুরোটা

প্রতিটি দলের নিজের আকার বানানোর বদলে IETF একটি সাধারণ আকার দিয়েছে। RFC 7807 (২০১৬) এর শুরু, আর জুলাই ২০২৩-এর RFC 9457 সেটিকে প্রতিস্থাপন করেছে। Media type application/problem+json. পাঁচটি মানক সদস্য, সবগুলোই ঐচ্ছিক:

এর বাইরে নিজের সদস্য যোগ করা যায়, আর client অচেনা সদস্য উপেক্ষা করবে। এটাই একে বাড়তে দেয়। type মূল পরিচয় হলেও বাজারঘরে আমরা সরল code-ও রাখছি, কারণ পর্ব ২৮-এর frontend সেটি পড়ে। পর্ব ২৮-এ instance-এ path রাখা হয়েছিল; সেটিও অনুমোদিত, তবে একই path-এ অনেক ঘটনা ঘটে, তাই এখানে urn:uuid: নিয়েছি। handler-এর কোড পর্ব ২৮-এ আছে, শুধু আকার বদলেছে। সত্যিকারের 422 উত্তর:

$ curl -si -X POST -H 'content-type: application/json' -H 'Authorization: Bearer token-rafi' \
    -d '{"sku":"x","qty":99}' http://127.0.0.1:47333/v1/orders
HTTP/1.1 422 Unprocessable Entity
Content-Language: bn
Vary: Accept-Language
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://bazarghar.example/problems/validation-failed",
  "title": "কিছু ঘরের তথ্য ঠিক নেই",
  "status": 422,
  "instance": "urn:uuid:05160637-2cd0-4bde-8068-f8efa5bd4f9a",
  "code": "VALIDATION_FAILED",
  "traceId": "05160637-2cd0-4bde-8068-f8efa5bd4f9a",
  "errors": [
    { "path": "sku", "code": "too_small", "message": "SKU কমপক্ষে ৩ অক্ষরের" },
    { "path": "qty", "code": "too_big", "message": "সর্বোচ্চ ১০টি" }
  ]
}

JSON-টি পড়ার সুবিধার জন্য সাজানো। ভাষা ঠিক হয় content negotiation দিয়ে: Accept-Language: en পাঠালে একই run-এ এলো "title":"Some fields are invalid" আর Content-Language: en. কিন্তু ওই run-এর errors-এর বার্তা বাংলাই রইল, কারণ Zod schema-য় বাংলা লিখে রাখা হয়েছিল। এটি আমাদের lab-এর একটি সত্যিকারের ত্রুটি, আর শিক্ষাও। বহুভাষী client-এর জন্য errors[].code ধরে অনুবাদ করা নিরাপদ, বার্তা দেখে নয়। বাংলা সাইটের i18n আছে পর্ব ৫৯-এ।

Client-এর দিকে কোডটি তাহলে সরল। লক্ষ করুন, title মিলিয়ে কোনো সিদ্ধান্ত নেই:

function showProblem(p, form) {
  switch (p.code) {
    case 'VALIDATION_FAILED':
      p.errors.forEach((e) => form.setError(e.path, { message: e.message }));
      break;
    case 'OUT_OF_STOCK':
      toast(`মজুত আছে ${p.available}টি`);
      break;
    default:
      toast(`${p.title} (কোড: ${p.traceId.slice(0, 8)})`);
  }
}

৬ · দুবার ক্লিক, দুবার টাকা: সমস্যাটি নিজে ঘটানো

আপনি মোবাইলে টাকা পাঠালেন। ঘুরতে ঘুরতে পর্দায় লেখা এলো “সংযোগ বিচ্ছিন্ন”। টাকা কি গেল? আবার পাঠাবেন? এই অস্বস্তি প্রত্যেকের চেনা। HTTP-তে ঠিক এটাই ঘটে। উত্তর না পাওয়া মানে কাজ না হওয়া নয়। অনুরোধটি হয়তো পৌঁছেছে, কাজ শেষ হয়েছে, শুধু উত্তর ফেরার পথে হারিয়েছে।

এটি কাল্পনিক নয়। বাজারঘরের POST /v1/orders-এ gateway-র কাজ লাগে ৪০০ ms. curl-কে ২০০ ms পরে থেমে যেতে বলা হলো, যেন মোবাইল নেটওয়ার্ক কেটে গেছে। সত্যিকারের run:

$ curl -sS --max-time 0.2 -X POST … -d '{"sku":"RICE-5KG","qty":1}' $API/v1/orders
curl: (28) Operation timed out after 212 milliseconds with 0 bytes received

$ curl -si -X POST … -d '{"sku":"RICE-5KG","qty":1}' $API/v1/orders    # ক্রেতা আবার চাপলেন
HTTP/1.1 201 Created
Location: /orders/2

{"id":2,"total":700}

$ curl -s $API/debug/ledger
{"orders":2,"charges":2,"charged":1400}

Client চলে গেলেও Node-এর handler থামেনি, কাজ শেষ করেছে। তাই order ২টি, আর কাটা গেছে ৳১,৪০০. $API এখানে http://127.0.0.1:47333, আর /debug/ledger শুধু lab-এর হিসাব দেখার জন্য।

ক্ষতির আকার হিসাব করুন। ধরুন দিনে ২,০০০ চেকআউট, ০.২% ক্ষেত্রে উত্তর হারায় আর ক্রেতা আবার চাপেন, গড় order ৳৭০০ (সব সংখ্যা ধরে নেওয়া)। তাহলে 2000 × 0.002 = ৪টি duplicate, মানে দিনে ৳২,৮০০ ভুল কাটা, আর ৪ জন রাগী ক্রেতা। শতাংশ ছোট, কিন্তু প্রতিটি ঘটনা সরাসরি টাকা।

কেন এমন হলো? কারণ POST idempotent নয়, দুবার পাঠালে দুবার কাজ। PUT আর DELETE নিজে থেকেই idempotent, তাই সেগুলো আবার পাঠানো যায়। অনেকে ভাবেন, একবার ক্লিকের পরে বোতাম বন্ধ করলেই সমস্যা শেষ। তা হয় না। disabled বোতাম শুধু একই পাতার দ্বিতীয় ক্লিক থামায়। পাতা reload, দুই tab, মোবাইলের back, আর library-র নিজের retry এতে থামে না। এখন ছোট মডেলে সমাধানের মূল ধারণা চালিয়ে দেখুন।

const http = require('node:http');
const orders = [];
const saved = new Map();   // key -> আগের উত্তর
const server = http.createServer((req, res) => {
  const key = req.headers['idempotency-key'];
  req.resume();
  req.on('end', () => {
    if (key && saved.has(key)) {
      res.writeHead(201, { 'Idempotency-Replayed': 'true' });
      return res.end(saved.get(key));
    }
    orders.push({ sku: 'RICE-5KG' });
    const body = JSON.stringify({ orderId: orders.length });
    if (key) saved.set(key, body);
    res.writeHead(201).end(body);
  });
});
async function post(url, headers = {}) {
  const r = await fetch(url, { method: 'POST', headers, body: '{"sku":"RICE-5KG"}' });
  const replay = r.headers.get('idempotency-replayed') ?? 'no';
  console.log(' ', r.status, await r.text(), 'replayed:', replay);
}
server.listen(0, '127.0.0.1', async () => {
  const url = `http://127.0.0.1:${server.address().port}/orders`;
  console.log('double click, no key');
  await post(url); await post(url);
  console.log('  orders saved:', orders.length);
  orders.length = 0;
  console.log('double click, same key');
  const headers = { 'Idempotency-Key': 'intent-7f3c' };
  await post(url, headers); await post(url, headers);
  console.log('  orders saved:', orders.length);
  server.closeAllConnections();
  server.close();
});

double click, no key
  201 {"orderId":1} replayed: no
  201 {"orderId":2} replayed: no
  orders saved: 2
double click, same key
  201 {"orderId":1} replayed: no
  201 {"orderId":1} replayed: true
  orders saved: 1

৭ · Idempotency key: জমানো, মেয়াদ আর একসাথে আসা duplicate

ধারণাটি সরল। Client প্রতিটি অভিপ্রায়ের জন্য একটি অনন্য key বানায়, যেমন “এই কার্টের এই চেকআউট”। সেই অভিপ্রায়ের সব retry একই key নিয়ে যায়। চায়ের দোকানের হিসাব খাতার মতো: “রসিদ ৪১৭ আগেই লেখা হয়েছে” দেখলে দোকানদার দ্বিতীয়বার লেখেন না, পুরোনো হিসাবটাই দেখান।

খসড়া অনুযায়ী key একটি string, আর UUID বা সমান এলোমেলো মান ব্যবহারের সুপারিশ আছে। নিচের ছয়টি প্রশ্নের উত্তর ঠিক করাই পুরো নকশা:

Key-কে ব্যবহারকারীর সাথে বাঁধা নিরাপত্তারও প্রশ্ন। খসড়াও সতর্ক করে: দুর্বল key অনুমান করা গেলে অন্যের জমানো উত্তর পড়া যেতে পারে। তাই format যাচাই, আর lookup-এ client-এর দেওয়া key-র সাথে নিজের জানা পরিচয় জোড়া। Fingerprint হলো body-র SHA-256 hash, যা দিয়ে “একই key, ভিন্ন body” ধরা পড়ে। পুরো body জমানোর দরকার হয় না।

মূল অংশটি হলো atomic claim. কোডের মধ্যে SELECT করে দেখে তারপর INSERT নয়, একটিমাত্র SQL, যা unique constraint-এর ওপর ভরসা করে:

function claimKey(userId, key, fp) {
  db.prepare('DELETE FROM idempotency_keys WHERE expires_at < ?').run(Date.now());
  const r = db.prepare(`INSERT INTO idempotency_keys
      (user_id, key, fingerprint, state, expires_at)
    VALUES (?, ?, ?, 'processing', ?)
    ON CONFLICT (user_id, key) DO NOTHING`)
    .run(userId, key, fp, Date.now() + KEY_TTL_MS);
  return r.changes === 1;           // আমি জিতলাম?
}

// handler-এর ভেতরে
if (!claimKey(req.user.id, key, fp)) {
  const row = readKey(req.user.id, key);
  if (row.fingerprint !== fp) throw new Problem(422, 'IDEMPOTENCY_KEY_REUSED');
  if (row.state === 'processing') {
    res.set('Retry-After', '1');
    throw new Problem(409, 'REQUEST_IN_PROGRESS');
  }
  res.set('Idempotency-Replayed', 'true').location(row.location);
  return res.status(row.status).type('application/json').send(row.body);
}

await charge(`${req.user.id}:${key}`, total);   // একই key নিচেও যায়
db.exec('BEGIN');
// order লেখা আর জমানো উত্তর লেখা একই transaction-এ
db.exec('COMMIT');

BEGIN আর COMMIT অবহেলার নয়। Order লেখা হলো কিন্তু key “done” হলো না, এই অবস্থা transaction ছাড়া সম্ভব, আর তখন retry-তে দ্বিতীয় order. Transaction-এর পুরো গল্প পর্ব ৪৩-এ। এখন একই POST-এর সত্যিকারের run. আগের মতোই প্রথমটি মাঝপথে কাটা গেল:

$ K=7f3c1a52-9d4e-4b6a-8c21-0e5d3f6a7b10
$ curl -sS --max-time 0.2 -X POST … -H "Idempotency-Key: $K" -d '{"sku":"RICE-5KG","qty":1}' $API/v2/orders
curl: (28) Operation timed out after 208 milliseconds with 0 bytes received

$ curl -si -X POST … -H "Idempotency-Key: $K" -d '{"sku":"RICE-5KG","qty":1}' $API/v2/orders   # সাথে সাথে
HTTP/1.1 409 Conflict
Retry-After: 1

{"type":"…/request-in-progress","title":"আগের অনুরোধটি এখনো চলছে","status":409,…}

$ sleep 1
$ curl -si -X POST … -H "Idempotency-Key: $K" -d '{"sku":"RICE-5KG","qty":1}' $API/v2/orders
HTTP/1.1 201 Created
Idempotency-Replayed: true
Location: /orders/1

{"id":1,"total":700}

$ curl -s $API/debug/ledger
{"orders":1,"charges":1,"charged":700}

$ curl -si -X POST … -H "Idempotency-Key: $K" -d '{"sku":"RICE-5KG","qty":2}' $API/v2/orders   # অন্য body
HTTP/1.1 422 Unprocessable Entity

{"type":"…/idempotency-key-reused","title":"একই key ভিন্ন তথ্যে ব্যবহার করা হয়েছে","status":422,…}

৳১,৪০০ নেমে ৳৭০০, order ২টি নেমে ১টি। পুরো যাত্রাটি ধাপে ধাপে দেখুন। সরলতার জন্য এখানে retry এসেছে প্রথমটি শেষ হওয়ার পরে।

1client: new key2api: claim key3api: charge 7004api: order + reply5api: 201 (lost)6client: same key7api: replay 201

একসাথে আসা duplicate

দুবার ক্লিক একই সাথে হলে দুটি অনুরোধ একই মুহূর্তে চলে। “আগে দেখি key আছে কি না” পদ্ধতি এখানে ভাঙে: দুজনেই দেখে নেই, দুজনেই লেখে। এটি একটি race condition. মডেলে চালিয়ে দেখুন, একই key-তে তিনটি অনুরোধ একসাথে।

const http = require('node:http');
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
// ভুল: আগে দেখা, মাঝে database-এর এক ঘোরা, তারপর লেখা
async function checkThenWrite(keys, key) {
  const found = keys.has(key);
  await sleep(5);
  if (found) return false;
  keys.set(key, 'processing');
  return true;
}
// ঠিক: দেখা আর লেখা এক ধাপে, যেমন INSERT ... ON CONFLICT DO NOTHING
async function atomicClaim(keys, key) {
  if (keys.has(key)) return false;
  keys.set(key, 'processing');
  return true;
}
async function trial(name, claim) {
  const keys = new Map();
  let charges = 0;
  const server = http.createServer(async (req, res) => {
    const mine = await claim(keys, req.headers['idempotency-key']);
    if (!mine) return res.writeHead(409).end();
    await sleep(30);          // gateway-কে টাকা কাটতে বলা
    charges += 1;
    res.writeHead(201).end();
  });
  await new Promise((r) => server.listen(0, '127.0.0.1', r));
  const url = `http://127.0.0.1:${server.address().port}/`;
  const send = () => fetch(url, { method: 'POST', headers: { 'Idempotency-Key': 'k1' } });
  const replies = await Promise.all([send(), send(), send()]);
  console.log(name, replies.map((r) => r.status).sort().join(' '), '| charges:', charges);
  server.closeAllConnections();
  server.close();
}
trial('check-then-write', checkThenWrite).then(() => trial('atomic claim    ', atomicClaim));

check-then-write 201 201 201 | charges: 3
atomic claim     201 409 409 | charges: 1

request 2 -> 409
request 3 -> 409
request 1 -> 201
ledger: {"orders":1,"charges":1,"charged":700}

ব্যর্থ হলে key-এর কী হবে

Gateway বন্ধ থাকলে 503. কাজ হয়নি, তাই আমরা key মুছে দিই, যাতে retry নতুন করে চলে। কিন্তু 504 হলে? gateway হয়তো টাকা কেটেছে, উত্তরটি হারিয়েছে। তখন retry আবার gateway-তে যাবে। এখানেই key-কে নিচের স্তরেও পাঠানো জরুরি। Lab-এর gateway একই key দ্বিতীয়বার পেলে আর টাকা কাটে না। সত্যিকারের run:

# gateway টাকা কাটল, কিন্তু তার উত্তর হারাল
HTTP/1.1 504 Gateway Timeout
Retry-After: 1
--- ledger: {"orders":0,"charges":1,"charged":700}

# একই key-তে retry
HTTP/1.1 201 Created
Location: /orders/1
--- ledger: {"orders":1,"charges":1,"charged":700}

মাঝের লাইনটি ভয়ের: টাকা কাটা, order নেই। পরের retry সেটি মেলাল। আসল gateway-র idempotency কতক্ষণ থাকে, সেটি তার ডকুমেন্ট বলবে; পর্ব ৬৫-তে webhook সহ পুরো ছবি। আর যদি process মাঝপথে মরে যায়? Key processing-এই আটকে থাকবে, retry পাবে চিরকাল 409. তাই বাস্তবে এতে একটি lease লাগে: নির্দিষ্ট সময় পেরোলে অন্য অনুরোধ দখল নিতে পারবে, আর gateway-র key-র কারণে সেটি নিরাপদ। আমাদের lab-এ lease লেখা হয়নি, এটি নকশার কথা, চালানো হয়নি।

মেয়াদ: কতদিন মনে রাখবেন

খসড়া কোনো নির্দিষ্ট সময় বলে না; বলে মেয়াদ ঠিক করে ডকুমেন্টে প্রকাশ করতে। সময়টি হওয়া উচিত আপনার client-এর সবচেয়ে লম্বা retry-র চেয়ে বেশি। কম হলে কী হয়, তা ইচ্ছা করে করে দেখা হলো: মেয়াদ ১.৫ সেকেন্ড, retry ২ সেকেন্ড পরে।

HTTP/1.1 201 Created
Location: /orders/1

# ২ সেকেন্ড পরে একই key
HTTP/1.1 201 Created
Location: /orders/2
--- ledger: {"orders":2,"charges":1,"charged":700}

Key ভুলে যাওয়ায় দ্বিতীয় order হলো। Charge ১টিই, কারণ lab-এর gateway এখনো key মনে রেখেছে; আসল জীবনে সেটিরও মেয়াদ আছে। উল্টো দিকে খরচ আছে:

এখানে সেকেন্ডে ৫০টি POST আর ২ KB ধরে নেওয়া সংখ্যা। শিক্ষাটি হলো, আকার বাড়ে মেয়াদের সাথে সরলরেখায়, তাই পুরোনো সারি নিয়মিত মুছতে হয়। আমাদের কোডে সেটি প্রতিটি claim-এ হচ্ছে, যা ছোট lab-এ চলে। বড় টেবিলে একটি আলাদা cron কাজ ভালো (পর্ব ৬২). Key কোথায় থাকবে? Order-এর সাথে একই database-এ রাখলে একই transaction পাওয়া যায়, আর সেটিই বড় সুবিধা। আলাদা cache-এ রাখলে দ্রুত, কিন্তু “এক সাথে লেখা” আর থাকে না।

React থেকে key পাঠানো

Key-এর জন্ম ক্লিকে নয়, অভিপ্রায়ে। নিচের অংশটি উদাহরণ, এখানে চালানো হয়নি। পর্ব ১৯-এর useMutation-এর ওপর এটি লেখা।

const keyRef = useRef(crypto.randomUUID());   // চেকআউট শুরুতে একবার

const pay = useMutation({
  mutationFn: (cart) => api.post('/v2/orders', cart, {
    headers: { 'Idempotency-Key': keyRef.current },
  }),
  retry: (count, err) => count < 2 && [503, 504].includes(err.status),
  onSuccess: () => { keyRef.current = crypto.randomUUID(); },
});
// কার্ট বদলালেও নতুন key দিন, নইলে 422 আসবে

৮ · নিরাপদ retry, Retry-After আর rate limit header

এখন client-এর পুরো সিদ্ধান্ত এক জায়গায় আনা যায়। শর্ত দুটি: ভুলটি কি সাময়িক, আর আবার পাঠানো কি নিরাপদ? GET সবসময় নিরাপদ, PUT আর DELETE নকশামতো হলে নিরাপদ, POST নিরাপদ শুধু key থাকলে। Exponential backoff, jitter আর retry storm-এর হিসাব আছে পর্ব ২৮-এ; এখানে শুধু সিদ্ধান্তটি। নিচের block-এ একটি ছোট server নির্দিষ্ট ক্রমে code ফেরায়, আর client ঠিক করে আবার যাবে কি না। অপেক্ষার সময় শুধু হিসাব হচ্ছে, যাতে block দ্রুত শেষ হয়।

const http = require('node:http');
const server = http.createServer((req, res) => {
  const steps = req.url.slice(1).split('/');           // যেমন /503:2/200
  const [status, wait] = steps[Number(req.headers['x-try'])].split(':');
  if (wait) res.setHeader('Retry-After', wait);
  res.writeHead(Number(status)).end();
});
function shouldRetry(method, status, hasKey) {
  const temporary = [408, 429, 502, 503, 504].includes(status);
  return temporary && (method === 'GET' || hasKey);    // POST শুধু key থাকলে
}
async function send(base, method, path, hasKey) {
  let waited = 0;
  const trail = [];
  for (let attempt = 0; attempt < 3; attempt++) {
    const r = await fetch(base + path, { method, headers: { 'x-try': String(attempt) } });
    trail.push(r.status);
    if (r.ok || !shouldRetry(method, r.status, hasKey) || attempt === 2) break;
    const after = r.headers.get('retry-after');
    waited += after ? Number(after) * 1000 : 100 * 2 ** attempt;   // শুধু হিসাব, আসল ঘুম নয়
  }
  console.log(method.padEnd(4), hasKey ? 'key   ' : 'no key', trail.join(' > ').padEnd(15), `wait ${waited} ms`);
}
server.listen(0, '127.0.0.1', async () => {
  const base = `http://127.0.0.1:${server.address().port}`;
  await send(base, 'GET', '/503:2/200', false);
  await send(base, 'GET', '/502/504/200', false);
  await send(base, 'POST', '/503:2/201', false);
  await send(base, 'POST', '/504/201', true);
  await send(base, 'POST', '/422/201', true);
  await send(base, 'GET', '/500/200', false);
  await send(base, 'GET', '/429:1/429:1/429:1', false);
  server.closeAllConnections();
  server.close();
});

GET  no key 503 > 200       wait 2000 ms
GET  no key 502 > 504 > 200 wait 300 ms
POST no key 503             wait 0 ms
POST key    504 > 201       wait 100 ms
POST key    422             wait 0 ms
GET  no key 500             wait 0 ms
GET  no key 429 > 429 > 429 wait 2000 ms

Retry-After

RFC 9110 অনুযায়ী এর মান দুই রকম হতে পারে: সেকেন্ডের সংখ্যা (Retry-After: 120), অথবা একটি HTTP তারিখ। Client-এর কোড দুটিই বুঝতে পারলে ভালো। মান ০ বা ভুল হলে নিজের backoff-এ ফিরুন, আর একটি সর্বোচ্চ সীমা রাখুন; একটি ভুল header যেন client-কে এক ঘণ্টা আটকে না রাখে। 429 আর 503-তে এটি বেশি দেখা যায়, 202 বা 3xx-এও পাঠানো যায়।

Rate limit header

পর্ব ২৬-এর express-rate-limit (8.7.2) দিয়ে /search-এ মিনিটে ৩টি অনুরোধের সীমা দেওয়া হলো। চতুর্থ অনুরোধের সত্যিকারের উত্তর:

app.get('/search', rateLimit({
  windowMs: 60_000, limit: 3,
  standardHeaders: 'draft-8', legacyHeaders: false,
  handler: (req, res, next) => next(new Problem(429, 'RATE_LIMITED')),
}), search);

$ curl -si http://127.0.0.1:47333/search    # তৃতীয়বার
HTTP/1.1 200 OK
RateLimit: "3-in-1min"; r=0; t=60
RateLimit-Policy: "3-in-1min"; q=3; w=60; pk=:MTJjYTE3YjQ5YWYy:

$ curl -si http://127.0.0.1:47333/search    # চতুর্থবার
HTTP/1.1 429 Too Many Requests
RateLimit: "3-in-1min"; r=0; t=60
RateLimit-Policy: "3-in-1min"; q=3; w=60; pk=:MTJjYTE3YjQ5YWYy:
Retry-After: 60
Content-Type: application/problem+json; charset=utf-8

{"type":"…/rate-limited","title":"খুব বেশি অনুরোধ, একটু পরে চেষ্টা করুন","status":429,…}

q হলো কোটা, w সময়ের জানালা, r বাকি অনুরোধ, t জানালা শেষ হতে বাকি সেকেন্ড। ভালো client r=0 দেখেই থামতে পারে, 429 খাওয়ার আগেই। মান কিন্তু এখনো স্থির নয়। RateLimit header IETF-এর একটি সক্রিয় খসড়া (draft-ietf-httpapi-ratelimit-headers-11, মে ২০২৬), আর library-র 'draft-8' নামটিই বলছে সে কোন খসড়া মানে। খসড়া ১১-এর উদাহরণের লেখার ধরন একটু আলাদা, যেমন "default";r=50;t=30. বহু পুরোনো API এখনো X-RateLimit-* দেয়, যার কোনো মান নেই আর API ভেদে অর্থ বদলায়। তাই যে API ডাকবেন তার ডকুমেন্ট পড়ুন। Limit-এর algorithm আছে System Design কোর্সের rate limiting পর্বে.

৯ · Conditional request: ETag, 304 আর 412

একই খাতায় দুজন হিসাব লিখছেন। মিনা দাম লিখে গেলেন, রাফি পুরোনো ফটোকপি দেখে তার ওপর নিজের দাম লিখলেন। মিনার কাজ নীরবে মুছে গেল। কেউ কোনো ভুল বার্তা পেলেন না। এই হলো lost update. ফটোকপিতে যদি একটি সংস্করণ নম্বর থাকত, রাফি দেখতেন খাতা এগিয়ে গেছে।

ETag ঠিক সেই নম্বর, একটি resource-এর বর্তমান রূপের পরিচয়। এর ওপর ভর করে দুটি conditional request:

const http = require('node:http');
const item = { price: 700, version: 1 };
const etag = () => `"v${item.version}"`;
const server = http.createServer((req, res) => {
  if (req.method === 'GET') {
    if (req.headers['if-none-match'] === etag()) {
      return res.writeHead(304, { ETag: etag() }).end();
    }
    return res.writeHead(200, { ETag: etag() }).end(JSON.stringify(item));
  }
  const ifMatch = req.headers['if-match'];
  if (!ifMatch) return res.writeHead(428).end();
  if (ifMatch !== etag()) return res.writeHead(412, { ETag: etag() }).end();
  item.price = Number(req.headers['x-price']);
  item.version += 1;
  res.writeHead(200, { ETag: etag() }).end(JSON.stringify(item));
});
async function call(label, url, opts) {
  const r = await fetch(url, opts);
  console.log(label.padEnd(21), r.status, r.headers.get('etag') ?? '-', await r.text());
  return r.headers.get('etag');
}
const patch = (price, tag) => ({ method: 'PATCH',
  headers: { 'x-price': String(price), ...(tag && { 'If-Match': tag }) } });
server.listen(0, '127.0.0.1', async () => {
  const url = `http://127.0.0.1:${server.address().port}/products/1`;
  const seen = await call('GET', url);
  await call('GET again', url, { headers: { 'If-None-Match': seen } });
  await call('Mina PATCH 720', url, patch(720, seen));
  await call('Rafi PATCH 650 (old)', url, patch(650, seen));
  await call('PATCH without tag', url, patch(1));
  await call('GET with old tag', url, { headers: { 'If-None-Match': seen } });
  server.closeAllConnections();
  server.close();
});

GET                   200 "v1" {"price":700,"version":1}
GET again             304 "v1"
Mina PATCH 720        200 "v2" {"price":720,"version":2}
Rafi PATCH 650 (old)  412 "v2"
PATCH without tag     428 -
GET with old tag      200 "v2" {"price":720,"version":2}

আসল Express-এ GET-এর দিকে কাজ প্রায় নেই। Handler ETag বসালে res.json নিজেই If-None-Match মিলিয়ে 304 পাঠায়, সত্যিকারের run:

$ curl -si -H 'If-None-Match: "v1"' http://127.0.0.1:47333/products/1
HTTP/1.1 304 Not Modified
ETag: "v1"
Cache-Control: no-cache

PATCH-এর দিকে Express কিছু করে না। আর সেখানে if (etag !== current) লিখে পরের লাইনে UPDATE করলে একই race ফিরে আসে। তাই যাচাই আর লেখা একই SQL-এ:

const ifMatch = req.get('If-Match');
if (!ifMatch) throw new Problem(428, 'PRECONDITION_REQUIRED');

const m = /^"v(\d+)"$/.exec(ifMatch);
const r = db.prepare(`UPDATE products
    SET price = ?, version = version + 1
    WHERE id = ? AND version = ?`)
  .run(price, id, m ? Number(m[1]) : -1);

const p = findProduct(id);
if (!p) throw new Problem(404, 'PRODUCT_NOT_FOUND');
if (r.changes === 0) {
  throw new Problem(412, 'STALE_VERSION', { currentEtag: `"v${p.version}"` });
}
res.set('ETag', `"v${p.version}"`).json(p);

একে বলে optimistic concurrency: আগে থেকে কিছু আটকে রাখা নয়, লেখার মুহূর্তে যাচাই। দুজন admin-এর একই পণ্য বদলানোর সত্যিকারের ঘটনাটি ধাপে ধাপে দেখুন।

HTTP/1.1 200 OK
ETag: "v1"
{"sku":"RICE-5KG","price":700,"version":1}

If-Match: "v1"   // price: 720
UPDATE ... WHERE id = 1 AND version = 1   -- 1 সারি
HTTP/1.1 200 OK
ETag: "v2"

If-Match: "v1"   // price: 650
UPDATE ... WHERE id = 1 AND version = 1   -- 0 সারি
HTTP/1.1 412 Precondition Failed
{"code":"STALE_VERSION",
 "title":"অন্য কেউ এটি আগেই বদলেছেন",
 "currentEtag":"\"v2\""}

HTTP/1.1 200 OK
ETag: "v2"
{"sku":"RICE-5KG","price":720,"version":2}
// দাম ৭২০ হয়েছে। আপনার ৬৫০ কি তবু রাখবেন?

If-Match: "v2"   // price: 650
HTTP/1.1 200 OK
ETag: "v3"
{"sku":"RICE-5KG","price":650,"version":3}

Weak আর strong

আমাদের "v1" নিজের বানানো strong ETag. Express নিজে থেকে যা বসায়, তা body-র hash থেকে তৈরি weak ETag: ETag: W/"7a-Y9ZtARp/0QbC65Q4B7t5B5X0YfE". RFC 9110 বলে If-None-Match weak তুলনা করে, আর If-Match strong তুলনা করে। তাই সত্যিকারের run-এ If-Match: W/"v2", যদিও version মিলছে, 412 পেয়েছে। পড়ার জন্য weak ঠিক আছে, লেখার পাহারায় নয়।

আরেকটি জিনিস run-এ ধরা পড়েছে। Express ভুলের উত্তরেও নিজের weak ETag বসায়; আমাদের 412-র উত্তরে ছিল ETag: W/"130-…", যেটি error body-র hash, পণ্যের সংস্করণ নয়। তাই client শুধু 2xx-এর ETag মনে রাখবে, আর পরের সংস্করণ নেবে currentEtag থেকে। উপরে পেস্ট করা উত্তরে এই লাইনগুলো ছোট করা হয়েছে।

কত বাঁচে: একটি হিসাব

ধরুন পণ্যের তালিকার JSON ২০০ KB, ১,০০০ জন ব্যবহারকারী প্রতি ৩০ সেকেন্ডে poll করেন, আর ৯৫% সময় কিছু বদলায় না। 304-এর উত্তর ধরি ০.৩ KB (সবই ধরে নেওয়া সংখ্যা)। এক ঘণ্টায়:

ব্যান্ডউইথ প্রায় ৯৫% কমেছে, যা 1 − 1234 ÷ 24000 ≈ 0.949. কিন্তু সাবধান: Express-এর স্বয়ংক্রিয় ETag বানাতে body তৈরি করতে হয়, তাই database query আর CPU বাঁচে না, বাঁচে শুধু নেটওয়ার্ক। Version-এর মতো সস্তা চিহ্ন আগে দেখলে তবেই query-ও বাঁচে। HTTP cache-এর পুরো ছবি আছে Computer Networks কোর্সের web caching পর্বে আর পর্ব ৮৪-তে।

১০ · AI-এর যুগে: API-র ভুলের পথ যাচাই

AI দিয়ে লেখা API সুখের পথে সুন্দর চলে। দুবার ক্লিক, হারানো উত্তর আর দুজনের একসাথে লেখা, এগুলো কোনো demo-তে ঘটে না। Idempotency-র কোড দেখতে ঠিক লাগলেও atomic না হলে কাজ করে না, আর সেটি শুধু একসাথে অনুরোধ পাঠালেই ধরা পড়ে।

AI-এর লেখা API হাতে পেলে

• প্রতিটি ভুলের status আর body curl দিয়ে দেখেছি, শুধু কোড পড়িনি
• সব ভুল একই আকারে আসে, Content-Type সহ
• অন্যের জিনিস আর না-থাকা জিনিসে হুবহু একই 404 পেয়েছি
• --max-time দিয়ে উত্তর হারিয়ে retry করেছি, আর হিসাব মিলিয়েছি
• একই key-তে একসাথে অনুরোধ পাঠিয়ে একটিই charge পেয়েছি
• পুরোনো ETag-এ PATCH করে 412 পেয়েছি, আর মান অক্ষত দেখেছি
• Header-এর মান RFC না খসড়া, সেটি নিজে দেখেছি, আর অদরকারি package বাদ দিয়েছি