René's URL Explorer Experiment


Title: fix(v2): tell a caller when to come back on every failure meant to be retried by waleedlatif1 · Pull Request #6625 · simstudioai/sim · GitHub

Open Graph Title: fix(v2): tell a caller when to come back on every failure meant to be retried by waleedlatif1 · Pull Request #6625 · simstudioai/sim

X Title: fix(v2): tell a caller when to come back on every failure meant to be retried by waleedlatif1 · Pull Request #6625 · simstudioai/sim

Description: Three related gaps in retry signalling on the v2 surface, found auditing it against RFC 9110 / RFC 6585 and against how Stripe, GitHub and Google's AIPs handle the same problems. Builds on #6620. What was wrong 1. No 503 carried Retry-After. Not one of them: the three route builders' unhandledErrorResponse, the execute and resume routes, and serviceFailureResponse. A client's only defensible policy on a bare 503 is an immediate retry — which is exactly the traffic a degraded dependency cannot absorb, and Sim raises 503 precisely when the API-key store, the rollout gate, the rate-limit backend, or execution-identity allocation is briefly unavailable. 2. A 429 that already knew its wait threw it away. This is the more interesting one. ADMISSION_ERROR_DESCRIPTOR declares retryAfterSeconds: 5 for RESERVATION_CONCURRENCY, but mapping a descriptor onto a PreprocessExecutionError copied only statusCode, code and retryable. A concurrency denial therefore reached the client as a bare 429 with no Retry-After — despite the policy layer having named the wait five seconds earlier, and despite the OpenAPI already documenting RateLimited.headers: ['Retry-After']. The 503 infrastructure denial had the same leak; the new default happened to mask it with the same number. 3. One 503 must not advise a retry at all. ASYNC_ENQUEUE_AMBIGUOUS means the enqueue may have succeeded — it deliberately retains its execution-ID claim because a job may already exist. Telling that caller to come back in 5s invites a client with no X-Run-Id to start, and bill, a second run of the same workflow. What changed v2Error applies a Retry-After default keyed on the response status (not the v2 error code — Retry-After is defined against the status, and the status is the only half of the pair a client sees). A caller-supplied value still wins. retryAfterSeconds now travels descriptor → PreprocessExecutionError.retryAfterMs → ExecuteWorkflowServiceFailure.retryAfterMs → serviceFailureResponse. The transport reads a number the policy owns instead of re-guessing it; the v2Error default is now only the floor for paths with no policy signal. ASYNC_ENQUEUE_AMBIGUOUS opts out via omitRetryAfter and returns the run id so the caller reconciles rather than retries. Reuses ADMISSION_RETRY_AFTER_SECONDS rather than restating 5, so the execute route's capacity 429 and every other surface's 503 cannot drift apart. One central OpenAPI edit adds Retry-After to the shared ServiceUnavailable response — all 128 operations, 7 specs. The audit .agents/skills/v2-api-conventions/SKILL.md records the standards review so it is not re-litigated: the retry rule, the cursor-tamper-evidence invariants, and reasoned rejections of RFC 9457 problem+json, the IETF RateLimit-* draft fields, renaming X-RateLimit-* under RFC 6648, 422-for-semantic-validation, Location on 201, ETag / If-Match, and merge-patch+json — each with the spec text and the industry evidence. Highlights of the "no" cases, since the evidence was not what I expected: RFC 6648 does not ask anyone to rename deployed X- headers. §1 item 4 "makes no recommendation as to whether existing 'X-' parameters ought to remain in use or be migrated", and Appendix B argues the migration is the interoperability harm. The rule is a SHOULD NOT binding creators of new parameters. The RateLimit-* draft is unpublished, was returned "Not ready" at HTTPDIR review, and is on its third mutually incompatible wire format. 0 of Stripe/GitHub/Google emit it. 0 of 3 use RFC 9457, and 9457 §4 itself steers APIs with an existing format toward keeping it. 0 of 3 do HTTP optimistic concurrency. Google does the semantics via a resource etag field (AIP-154), deliberately not If-Match. Retry-After is only a MAY on 429 and 503 — it is SHOULD on exactly one status, 413. So this PR is a deliberate improvement, not a conformance fix, and says so. Deprecation/Sunset on v1 is left open: emitting either commits Sim to a retirement date, which is a product decision, not an engineering one. Idempotency is assessed and deliberately not extended here. X-Run-Id already gives the money path at-most-once semantics via a durable claim, and the operation description already says it is not an idempotency key. A true Stripe-style Idempotency-Key needs a request fingerprint, a retention window, an in-flight-vs-completed split, and somewhere to store a large synchronous body — a designed piece of work, not an increment. Aliasing the header name without the replay semantics would be worse than leaving it, since clients written against Stripe would read our 409 as a hard failure. Verification Every fix has a test proven to fail without it (reverted the source, watched it go red, restored). bun run type-check, check:api-validation, check:openapi (7 specs, 128 operations, 225 examples), biome on all changed files, and 1299 tests across the v2 / routes / execution / billing suites — all green.

Open Graph Description: Three related gaps in retry signalling on the v2 surface, found auditing it against RFC 9110 / RFC 6585 and against how Stripe, GitHub and Google's AIPs handle the same problems. Builds on #662...

X Description: Three related gaps in retry signalling on the v2 surface, found auditing it against RFC 9110 / RFC 6585 and against how Stripe, GitHub and Google's AIPs handle the same problems. Builds on ...

Opengraph URL: https://github.com/simstudioai/sim/pull/6625

X: @github

direct link

Domain: github.com

react-profiling0
react-import-mapreact,react-dom,react-dom/client,react-dom/profiling,react-is,react-reconciler,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@d5750093facf
route-pattern/:user_id/:repository/pull/:id/files(.:format)
route-controllerpull_requests
route-actionfiles
fetch-noncev2:5d1deccc-443c-33df-97e5-8a13790adfde
current-catalog-service-hashae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b
request-idCE52:14467D:35D056:4BA2C1:6AFB56F4
html-safe-nonce5157132f34acb05668d7d1cd92de146561fa68cd52e81a0b7deeadcf201a8739
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJDRTUyOjE0NDY3RDozNUQwNTY6NEJBMkMxOjZBRkI1NkY0IiwidmlzaXRvcl9pZCI6Ijc5NTEyNDgwMzMxODQ0MzgwMDQiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmacad55d495a12555da2abb1937ef46522718e01f7a02feb05ea96e0f6cbb2d7b21
hovercard-subject-tagpull_request:4264151025
github-keyboard-shortcutsrepository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///pull_requests/show/files
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/simstudioai/sim/pull/6625/files
twitter:imagehttps://avatars.githubusercontent.com/u/40672544?s=400&v=4
twitter:cardsummary_large_image
og:imagehttps://avatars.githubusercontent.com/u/40672544?s=400&v=4
og:image:altThree related gaps in retry signalling on the v2 surface, found auditing it against RFC 9110 / RFC 6585 and against how Stripe, GitHub and Google's AIPs handle the same problems. Builds on #662...
og:site_nameGitHub
og:typeobject
hostnamegithub.com
expected-hostnamegithub.com
None7122bb414b542dba14d71a3f0b9f6fd2abce715b9f5912d082800563e6c806d1
turbo-cache-controlno-preview
diff-viewunified
go-importgithub.com/simstudioai/sim git https://github.com/simstudioai/sim.git
octolytics-dimension-user_id199344406
octolytics-dimension-user_loginsimstudioai
octolytics-dimension-repository_id912559512
octolytics-dimension-repository_nwosimstudioai/sim
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id912559512
octolytics-dimension-repository_network_root_nwosimstudioai/sim
turbo-body-classeslogged-out env-production page-responsive full-width
disable-turbotrue
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
releasecbf66c024bb6d10e6955baa7413c54cf13a201bb
ui-targetfull
theme-color#1e2327
color-schemelight dark

Links:

Skip to contenthttps://github.com/simstudioai/sim/pull/6625/files#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fsimstudioai%2Fsim%2Fpull%2F6625%2Ffiles
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fsimstudioai%2Fsim%2Fpull%2F6625%2Ffiles
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fpull_requests%2Fshow%2Ffiles&source=header-repo&source_repo=simstudioai%2Fsim
Reloadhttps://github.com/simstudioai/sim/pull/6625/files
Reloadhttps://github.com/simstudioai/sim/pull/6625/files
Reloadhttps://github.com/simstudioai/sim/pull/6625/files
simstudioaihttps://github.com/simstudioai
simhttps://github.com/simstudioai/sim
Codehttps://github.com/simstudioai/sim
Issues129 (129)https://github.com/simstudioai/sim/issues
Pull requests197 (197)https://github.com/simstudioai/sim/pulls
Actionshttps://github.com/simstudioai/sim/actions
Projectshttps://github.com/simstudioai/sim/projects
Security and qualityhttps://github.com/simstudioai/sim/security
Insightshttps://github.com/simstudioai/sim/pulse
Sign up for GitHub https://github.com/signup?return_to=%2Fsimstudioai%2Fsim%2Fissues%2Fnew%2Fchoose
terms of servicehttps://docs.github.com/terms
privacy statementhttps://docs.github.com/privacy
Sign inhttps://github.com/login?return_to=%2Fsimstudioai%2Fsim%2Fissues%2Fnew%2Fchoose
waleedlatif1https://github.com/waleedlatif1
staginghttps://github.com/simstudioai/sim/tree/staging
feat/v2-http-standardshttps://github.com/simstudioai/sim/tree/feat/v2-http-standards
Conversation 7 https://github.com/simstudioai/sim/pull/6625
Commits 2 https://github.com/simstudioai/sim/pull/6625/commits
Checks 30 https://github.com/simstudioai/sim/pull/6625/checks
Files changed https://github.com/simstudioai/sim/pull/6625/files
Please reload this pagehttps://github.com/simstudioai/sim/pull/6625/files
fix(v2): tell a caller when to come back on every failure meant to be retried https://github.com/simstudioai/sim/pull/6625/files#top
Show all changes 2 commits https://github.com/simstudioai/sim/pull/6625/files
6b1ab16 fix(v2): tell a caller when to come back on every failure meant to be… waleedlatif1 Aug 12, 2026 https://github.com/simstudioai/sim/pull/6625/commits/6b1ab169be0177578573ee6bffc0ba912ef1cde4
6de7ad9 docs(v2): name the one 503 that omits Retry-After in the shared contract waleedlatif1 Aug 12, 2026 https://github.com/simstudioai/sim/pull/6625/commits/6de7ad9fd244172eeb002eca85ac48f5429c499b
Clear filters https://github.com/simstudioai/sim/pull/6625/files
Please reload this pagehttps://github.com/simstudioai/sim/pull/6625/files
Please reload this pagehttps://github.com/simstudioai/sim/pull/6625/files
SKILL.md https://github.com/simstudioai/sim/pull/6625/files#diff-8ece2aa9a15122239fc217eb94d684ef57b385916b95bed160ad4b424543edc5
v2-api-conventions.md https://github.com/simstudioai/sim/pull/6625/files#diff-34b6597331f2a9dd49c38118ef0f0555424f9f0c762ce33549141e71f9c470c4
v2-api-conventions.md https://github.com/simstudioai/sim/pull/6625/files#diff-dc6f94499025928e979e62a01a870f67c12a2ce9e0622b4dcb33310eb23b968e
openapi-v2-billing.json https://github.com/simstudioai/sim/pull/6625/files#diff-d1a7579e3381b5f6f39f2f304f56201fbf944a23caa31b5ecc165988a85a6eb4
openapi-v2-files-audit.json https://github.com/simstudioai/sim/pull/6625/files#diff-c6918d7f933ec43ee8b8a4983d19f272b35962e2510bad721fc05d6d82b41b8d
openapi-v2-knowledge.json https://github.com/simstudioai/sim/pull/6625/files#diff-c15da3de30ec533f5aedd9a2862e8afdb8e2a58490fe681b97959638218bf99e
openapi-v2-logs.json https://github.com/simstudioai/sim/pull/6625/files#diff-303943bbe4957dfce964c583968a279a8fddba1850a9ada9273d00b5498f8a75
openapi-v2-resources.json https://github.com/simstudioai/sim/pull/6625/files#diff-17e168777a3b67e689dd8b24e28aaa217cb884843dccad31b1dbf22d5307e17f
openapi-v2-tables.json https://github.com/simstudioai/sim/pull/6625/files#diff-ce7e6e983230c870183cf99d3e224cd90a9b070ad038113d581d755a0386043b
openapi-v2-workflows.json https://github.com/simstudioai/sim/pull/6625/files#diff-811f737e7f97ec52156a37e71892822626b5b4de295efebd20992198d162149b
response.test.ts https://github.com/simstudioai/sim/pull/6625/files#diff-436a267a80be27a4da00f2aa51f74dbcf0541937faf561ce579e925424dbac05
response.ts https://github.com/simstudioai/sim/pull/6625/files#diff-5846b44ffd25e5e2483dcdd64d5cbb796d06236d4e86bb0d7a670b32b8220851
route.test.ts https://github.com/simstudioai/sim/pull/6625/files#diff-640f02761f3a7ac2ce0726010dfea4cc6ba4cc3857c8c815c105d77e95448268
route.ts https://github.com/simstudioai/sim/pull/6625/files#diff-252ea27fb82edabea096a178bbadb86ae68395d1d720c3855b3bbbdfe38251c7
shared.ts https://github.com/simstudioai/sim/pull/6625/files#diff-de04a2f2a3526e0173b51672e735d59e9172fb12b2ac2cee63190fb5dfc777b1
usage-reservation.ts https://github.com/simstudioai/sim/pull/6625/files#diff-c4a346abbf778d4c42f4af5a8ee905400038541d3055e83b56d3c3d635d3d2b8
preprocessing.test.ts https://github.com/simstudioai/sim/pull/6625/files#diff-bf810ff832cf89c1bf98cfe2ecb746f021b88001dc8a0bd0732de89cb289089a
preprocessing.ts https://github.com/simstudioai/sim/pull/6625/files#diff-302a95657ffed9f4b7bf818f94d31f82065f79bda02a09a46da02a6a3411aa21
.agents/skills/v2-api-conventions/SKILL.mdhttps://github.com/simstudioai/sim/pull/6625/files#diff-8ece2aa9a15122239fc217eb94d684ef57b385916b95bed160ad4b424543edc5
View file https://github.com/simstudioai/sim/blob/6de7ad9fd244172eeb002eca85ac48f5429c499b/.agents/skills/v2-api-conventions/SKILL.md
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/simstudioai/sim/pull/6625/{{ revealButtonHref }}
https://github.com/simstudioai/sim/pull/6625/files#diff-8ece2aa9a15122239fc217eb94d684ef57b385916b95bed160ad4b424543edc5
https://github.com/simstudioai/sim/pull/6625/files#diff-8ece2aa9a15122239fc217eb94d684ef57b385916b95bed160ad4b424543edc5
https://github.com/simstudioai/sim/pull/6625/files#diff-8ece2aa9a15122239fc217eb94d684ef57b385916b95bed160ad4b424543edc5
Please reload this pagehttps://github.com/simstudioai/sim/pull/6625/files
Please reload this pagehttps://github.com/simstudioai/sim/pull/6625/files
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.