Node 26.11 isValidHeaderValue: check a Sume Idempotency-Key first

Yes: since Node.js 26.11.0 you can call http.isValidHeaderValue(value) on the string you plan to send as Idempotency-Key and refuse to submit when it returns false. The 26.11.0 release notes list http.isValidHeaderName() and http.isValidHeaderValue() as new, and the http reference gives the signature as isValidHeaderValue(value[, options]) returning a boolean. It is a syntax check on one header value. It does not know anything about Sume.

Why bother? A key built from an order id, a customer note or a pasted string can contain a newline or a control character. A request with such a header fails inside your HTTP client before the server sees it, and if your retry wrapper treats every thrown error as transient, you can loop on a request that can never be sent. Checking the key once, up front, turns that into one clear error at the call site.

What the check covers and what it does not

The table lists the facts this post relies on. Sume accepts an Idempotency-Key header on submit routes: the same key with the same payload returns the original job, and a different payload under the same key returns a 409, as described in the jobs and results docs.

Node's helper answers only whether the string is a legal HTTP header value. It cannot tell you whether the key is a good key. Choosing a stable key per logical order, and keeping it across retries, is still your job.

Steps

• Build the key from stable business data, for example an order id plus a version, or a UUID you store with the order.
• Call the helper before the first request. If it is missing (Node 22, 24), fall back to http.validateHeaderValue(name, value), which throws on an illegal value.
• Send the same key on every retry of that submit. Never generate a new key inside a retry loop.
• On a 202 or 200, store the returned job id next to the key so a restarted process can poll instead of resubmitting.

Runnable sample

This script submits an async image job. It feature-detects the new helper and works on current LTS lines. Set SUME_API_KEY first; the call authenticates with the Authorization: Bearer header, one credential only.

import http from "node:http";

const base = process.env.SUME_BASE ?? "https://api.sume.com";
const key = process.env.ORDER_KEY ?? crypto.randomUUID();

function headerValueOk(value) {
  if (typeof http.isValidHeaderValue === "function") return http.isValidHeaderValue(value);
  try { http.validateHeaderValue("Idempotency-Key", value); return true; } catch { return false; }
}
if (!headerValueOk(key)) throw new Error("Idempotency-Key is not a legal header value");

const res = await fetch(`${base}/v1/images`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUME_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": key,
  },
  body: JSON.stringify({ model: "sume/auto", prompt: "ceramic mug on oak table", mode: "async" }),
});
console.log(res.status, key);

What Sume does not do

Sume does not validate your key format beyond what HTTP allows, and the Node helper does not tell you whether a key was already used. A reused key with an edited prompt is a 409, not a fresh job. If you need to change the prompt, use a new key; if you are retrying, send the identical body. Read the full rules in the image model docs before wiring retries.