docs(api): align idempotency contract#4841
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| | `409` | `Idempotency-Key` request still in progress, or another conflict such as duplicate webhook registration. | Yes for keyed in-flight requests - honor `Retry-After: 2`; otherwise no | | ||
| | `422` | `Idempotency-Key` reused with a different request body. | No - resend the original body or use a new key | | ||
| | `413` | Payload too large | No | |
There was a problem hiding this comment.
The 422 row was inserted before the existing 413 row, breaking the ascending numeric ordering that the rest of the table follows (405 → 409 → 422 → 413 → 429). Readers scanning for a specific code by number will find the table inconsistent.
| | `409` | `Idempotency-Key` request still in progress, or another conflict such as duplicate webhook registration. | Yes for keyed in-flight requests - honor `Retry-After: 2`; otherwise no | | |
| | `422` | `Idempotency-Key` reused with a different request body. | No - resend the original body or use a new key | | |
| | `413` | Payload too large | No | | |
| | `409` | `Idempotency-Key` request still in progress, or another conflict such as duplicate webhook registration. | Yes for keyed in-flight requests - honor `Retry-After: 2`; otherwise no | | |
| | `413` | Payload too large | No | | |
| | `422` | `Idempotency-Key` reused with a different request body. | No - resend the original body or use a new key | |
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
|
|
||
| - **Auth**: Clerk bearer + active entitlement | ||
| - **Response**: `{ "portalUrl": "..." }` | ||
| - **Idempotency**: optional `Idempotency-Key` supported. Retrying the same key replays the original portal response instead of creating another portal attempt. |
There was a problem hiding this comment.
POST /api/customer-portal
Every other endpoint's idempotency bullet explicitly states "with an identical body" to communicate that body-matching is required for replay. The customer-portal bullet omits this, which could mislead clients into thinking they can replay with a different body and still get the cached response (they'd actually receive 422 idempotency_key_reused).
| - **Idempotency**: optional `Idempotency-Key` supported. Retrying the same key replays the original portal response instead of creating another portal attempt. | |
| - **Idempotency**: optional `Idempotency-Key` supported. Retrying the same key with an identical body replays the original portal response instead of creating another portal attempt. |
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
…son — back under the ~1MB scanner cap (#4852) (#4853) Today's per-op doc injections (#4843 429 blocks, #4841 idempotency, #4844 examples) grew the minified public/openapi.json 752KB -> 1.04MB, crossing the ~1MB body cap orank's function-calling validator imposes: the Access check function-calling-compat flipped PASS -> 'API spec found but couldn't validate function calling compatibility' (score 91 -> 90). elevenlabs (1.8MB) and openrouter (1.5MB) hit the identical error path; sub-800KB specs get computed verdicts. Hoist the byte-identical non-2xx response objects (429 x193, default x193, 401 x186, 400, 403, 409, 422) into components.responses $refs when emitting the JSON artifact only - semantically identical OpenAPI 3.1, validated with @seriousme/openapi-schema-validator. 2xx responses stay inline (orank credits only the inline responses['200'] schema). YAML sources keep their inline copies for Mintlify and the contract tests. Result: 812,276 bytes (10 shared components, 975 refs), deterministic rebuild, lossless roundtrip proven by test. A 950KB budget guard test stops the next injector from silently re-crossing the cap. Claude-Session: https://claude.ai/code/session_013AWjvnpnJTE6G2PaYk9iT1
1 participant
Summary
WorldMonitor's API docs now describe
Idempotency-Keythe way the shipped OpenAPI contract and standalone handlers actually behave.run-scenariois documented as keyed-idempotent for retries, 409/422 guidance now matches the in-flight and payload-mismatch semantics, and the five standalone write endpoints from PR #4792 are called out in their API docs.The docs also spell out the client-retry limits that matter: retryable 5xx responses are not cached for replay, checkout replays are retained for 10 minutes, and idempotency keys are scoped to the authenticated caller or source IP.
Closes #4828.
Verification
/opt/homebrew/bin/gh-axi issue view 4828 --full/opt/homebrew/bin/gh-axi search prs "4828 OR idempotency OR Idempotency-Key"->count: 0node --test tests/docs-idempotency-contract.test.mjsnode --test tests/openapi-idempotency-contract.test.mjsnpm run lint:api-contractnpm run docs:check./node_modules/.bin/markdownlint-cli2 docs/usage-errors.mdx docs/api-commerce.mdx docs/api-notifications.mdx docs/api-platform.mdxgit push -u origin codex/docs-idempotency-contract-4828pre-push hook: typecheck, API typecheck, boundary/safe HTML/rate-limit/premium-fetch guards, edge bundle/tests, markdown/MDX lint, and version sync all passed