Skip to content

fix(facilitator): a refused call does not extend the window, and the 429 carries Retry-After - #108

Merged
pursekeeper merged 1 commit into
pursekeeper:mainfrom
manhliemcn4euwlu-source:fix/facilitator-429-only
Oct 23, 2026
Merged

pursekeeper merged 1 commit into
pursekeeper:mainfrom
manhliemcn4euwlu-source:fix/facilitator-429-only

Conversation

@manhliemcn4euwlu-source

Copy link
Copy Markdown
Contributor

What

facilitator.js overLimit pushed the timestamp of every request into the window before it decided whether the call was over the limit. A 429 therefore extended the window it was refused by, so a client retrying at the rate it was refused stayed over the limit for as long as it kept trying. The 429 also carried no Retry-After, so nothing told the client when the window would clear.

server.js overFreeLimit does this the other way round (check, then push; Retry-After on the refusal) since 2026-10-23, so the two surfaces disagreed on the same contract.

Measured on facilitator.pursekeeper.dev, 2026-10-23 ~06:2xZ

One host, POST /verify with {} (served as a 400 paymentPayload and paymentRequirements are required):

calls outcome
130 concurrent 400 x120, 429 x10
those 10 x 429 0 carried Retry-After

Same host, 150 sequential calls a few minutes later: 400 x150, no 429 (window had cleared). That difference is the tell: the concurrent run's own 429s were counting against the window.

Why it matters

The facilitator is the public settlement surface a resource server points its buyers at (/verify 120/min, /settle 60/min per IP). A client that treats a 429 as "retry now" — the normal shape when no Retry-After is given — holds itself over the limit indefinitely. /settle is the worse half: the call being refused is a payment the buyer already signed.

Fix

  • Only served calls extend the window.
  • The refusal sets Retry-After to the whole seconds until the oldest hit leaves the window, the same shape as server.js overFreeLimit.
  • overLimit is internal to the file, so the signature change (it now takes res) reaches no caller outside it.

Test evidence

  • New test in test/facilitator.test.js: 120 served /verify calls, the 121st answers 429 with Retry-After in 1..60, and a second refusal does not extend the window (its Retry-After must not grow).
  • Fails on the previous commit (git stash push -- facilitator.js -> not ok 24, 33 pass 1 fail) and passes with the change (34/34).

Scope

No change to the limit values, the counting of served calls, stats, or any wire format. Only the refusal path and its header.

Note on the earlier PR

#107 was cut from the #106 branch, so its diff carried the #106 changes as well. It is closed; this one carries only the facilitator change, so the two can be reviewed and merged independently.

Terms

Same class and size as api#104 (merged 2026-10-22, paid Ӿ1) and api#106 (open, Ӿ2 asked): a per-route counter that does not behave the way the surface promises. I am asking Ӿ2 on merge, or a refusal with the reason and the test left for the next person.

…429 carries Retry-After

The limiter pushed every request timestamp into the window before deciding
whether the call was over the limit, so a 429 extended the window it was refused
by: a client retrying at the rate it was refused stayed over the limit. The 429
also carried no Retry-After.

Measured on facilitator.pursekeeper.dev 2026-10-23: 130 concurrent POST /verify
from one host answered 400 x120 then 429 x10, and 0 of the ten carried
Retry-After, while pursekeeper.dev free routes answer 429 with Retry-After.

Now only served calls extend the window, and the refusal names the seconds until
the oldest hit leaves it. Regression test fails on the previous commit (33 pass
1 fail) and passes here (34/34).
@pursekeeper
pursekeeper merged commit ae8111e into pursekeeper:main Oct 23, 2026
pursekeeper pushed a commit that referenced this pull request Oct 23, 2026
…29 window + Retry-After), #109 (llmrt, receivable truncation flag), #110 (umpireboulianne-design, cohorts own-address row, repeat and funding after the fold); client-x402.js synced with skill 0.3.13 (cross-origin quote redirects refused, pyfile PR #7), the canonical-redirect case expects exit 6; test fixtures are synthetic accounts
@pursekeeper

Copy link
Copy Markdown
Owner

Merged as part of 407f273 (main 8cb92c0), live since 08:28:38Z; the facilitator runs in the same process, so the window rule and the Retry-After are on facilitator.pursekeeper.dev now. Verified here: 223 tests, 218 pass, 0 fail, data md5 unchanged.

Ӿ1, ledger entry 457, block BA5D87DF0F8A3883FE3505CE81E73A5623DA583DD4625910800206470322BB3F, priced like #104: tested correctness fix, no Nano loss path (a signed block refused with 429 stays re-presentable). Nothing owed on #107, which you closed as superseded.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants