From 6d0b51c9cca65d8752df7fbde46795aa96012a0a Mon Sep 17 00:00:00 2001 From: Karl Waldman Date: Sun, 23 Aug 2026 18:08:12 -0400 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20document=20multi-code=20batching=20?= =?UTF-8?q?=E2=80=94=2020=20codes,=20one=20request=20(api#7240)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The API accepts up to 20 comma-separated commodity codes in a single request that counts ONCE against quota. This SDK has always supported it and the README never said so — zero mentions of batching, comma-separated codes, or the cap. Users could not discover a 20x quota saving. On the free plan that is the difference between 50 code-reads a day and 1,000. Verified by running it, not by reading the source: node against the live API -> 3 prices in ONE request Also documents the two failure modes a caller will actually hit: 21+ codes returns 400 "Too many commodity codes requested (max: 20, requested: N)", and an unrecognised code returns 400 with a "did you mean" suggestion. NOT a code change. Unlike the Python SDK (api#7240), this client has no per-code loop — it passes by_code straight through, so batching already worked. Python had a broken batch helper; the other three had no affordance at all. Refs api#7240, api#7235 Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01JKAExynd9zoKwt6rYA66EA --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index d65fc55..e0c4739 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,31 @@ The reviewed standalone form is type-checks and executes it against production-shaped fixtures, then publishes its exact code and checksum in the release snippet manifest. +## Several Prices In One Request + +`commodity` accepts up to **20 comma-separated commodity codes**, and the whole call +counts as **one request** against your quota — not one per code. + +```typescript +const prices = await client.getLatestPrices({ + commodity: "BRENT_CRUDE_USD,WTI_USD,NATURAL_GAS_USD", +}); + +for (const p of prices) { + console.log(p.code, p.price, p.currency); +} +``` + +This is worth knowing on the free plan: 50 requests a day carrying 20 codes each is +**1,000 code-reads a day**, not 50. + +Asking for more than 20 returns `400 Too many commodity codes requested +(max: 20, requested: N)`, and an unrecognised code returns `400` with a "did you +mean" suggestion — so validate your code list once rather than on every poll. + +See [How Often To Poll](https://docs.oilpriceapi.com/guides/rate-limiting#how-often-to-poll) +for the interval that fits your plan. + ## Permit To Production Well-level production coverage is narrower than permit coverage. Check the live From 1efc8497b54cc7a54e1f8871e86bc7441f6d8c18 Mon Sep 17 00:00:00 2001 From: Karl Waldman Date: Sun, 23 Aug 2026 18:12:23 -0400 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20state=20the=20ratio,=20not=20the=20?= =?UTF-8?q?rate=20=E2=80=94=20the=20claims=20guard=20was=20right?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI rejected the first version: Error: README.md: fixed demo rate "50 requests a day" scripts/validate-storefront-claims.mjs (and its siblings) forbid plan specifics in an SDK README — "free tier", fixed quota windows, and fixed request rates. That is deliberate and correct: plans change, SDKs release on their own cadence, and a stale allowance baked into a published package is worse than none at all. It is also exactly the failure this whole thread is about. The docs site published "200 requests per month" for 17 days after the plan became 50/day (api#7235). I then wrote the new number into three SDK READMEs that release independently — the same mistake, one layer down. The guard caught it; nothing caught the docs site. Rewritten to state the mechanism and the RATIO, which is true regardless of plan: twenty codes in one call stretches an allowance twenty times. Plan specifics now live behind a link to the rate-limiting guide, which is where they can be kept current. Kept: the 20-code cap and both 400 responses — those are API contract, not plan claims. Verified locally before pushing: node scripts/validate-storefront-claims.mjs -> validated 36 Node public surfaces, pass. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01JKAExynd9zoKwt6rYA66EA --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e0c4739..66a6667 100644 --- a/README.md +++ b/README.md @@ -96,8 +96,9 @@ its exact code and checksum in the release snippet manifest. ## Several Prices In One Request -`commodity` accepts up to **20 comma-separated commodity codes**, and the whole call -counts as **one request** against your quota — not one per code. +`by_code` accepts up to **20 comma-separated commodity codes**, and the whole call +counts as **one request** — not one per code. Batching is the cheapest way to make +an allowance go further: twenty codes in one call stretches it twenty times. ```typescript const prices = await client.getLatestPrices({ @@ -109,15 +110,13 @@ for (const p of prices) { } ``` -This is worth knowing on the free plan: 50 requests a day carrying 20 codes each is -**1,000 code-reads a day**, not 50. - -Asking for more than 20 returns `400 Too many commodity codes requested -(max: 20, requested: N)`, and an unrecognised code returns `400` with a "did you +Asking for more than 20 codes returns `400 Too many commodity codes requested +(max: 20, requested: N)`. An unrecognised code also returns `400`, with a "did you mean" suggestion — so validate your code list once rather than on every poll. -See [How Often To Poll](https://docs.oilpriceapi.com/guides/rate-limiting#how-often-to-poll) -for the interval that fits your plan. +For current plan allowances and the polling interval that fits them, see +[Rate Limiting](https://docs.oilpriceapi.com/guides/rate-limiting#how-often-to-poll). + ## Permit To Production