Repository navigation
docs(api): publish per-plan limits and the codes refusals carry (PRO-2965) - #333
Open
prathamgarg911 wants to merge 2 commits into
Open
prathamgarg911 wants to merge 2 commits into
prathamgarg911 wants to merge 2 commits into
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
✅ Mintlify HygieneNo issues found. |
✅ OpenHack SummarySecurity review of docs(api): publish per-plan limits and the codes refusals carry (PRO-2965). 28 changed files; 0 findings at or above the low reporting threshold.
Confidence Score: 5/5No reportable security findings were detected in this scan. Security merge-readiness rubric: 1 = critical, 2 = high, 3 = medium, 4 = low, 5 = no reportable findings. This score reflects scan findings, not a guarantee of correctness or complete coverage. Files Needing Attention: None Important Files Changed
Last reviewed commit: 8aa7e6d · View review on OpenHack
|
![openhack-agent[bot]](https://avatars.githubusercontent.com/in/2637932?s=60&v=4){kind=small}
…2965) The error reference said "Contact founders@hydradb.com for current limit values" while the API refused requests against numbers published nowhere. This publishes the per-plan limits table (query, ingest, items, upload volume, context volume, monthly tokens, storage, connectors) and what each refusal looks like, documents 402 PLAN_LIMIT_REACHED (monthly and storage caps, with reset date and upgrade link), 403 PLAN_UNRESOLVED (a key whose workspace has no plan on record), 410 ENDPOINT_RETIRED (retired v1 routes), the JSON 404 for unknown paths, Retry-After on every 429, and the 413 as a per-request allowance. Every v1 page carries a retirement notice naming the v2 reference, through one snippet. Companion to hydradb-application PRO-2965 (honest error semantics). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Pratham Garg <pratham@hydradb.com>
prathamgarg911
force-pushed
the
pratham/pro-2965-error-semantics-docs
branch
from
October 26, 2026 16:28
ba14361 to
c53c6ef
Compare
Contributor
 [Low impact] The PR appears safe to merge alongside or after the companion application change, as planned. SummaryThe PR publishes plan limits and error codes, and adds a shared v1 retirement notice.
Reviews (2) · Last reviewed commit: "docs(api): the raw fetch retry example w..." · Reviewed by Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
The retry pattern says to honour Retry-After on every 429, and the SDK examples do through the SDKs; the raw fetch example still backed off 1, 2 and 4 seconds. It reads Retry-After (seconds or an HTTP-date) and falls back to exponential backoff only when the server did not say. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Pratham Garg <pratham@hydradb.com>
SohamRatnaparkhi
approved these changes
Oct 27, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The v2 error reference said "Contact founders@hydradb.com for current limit values" while the API refused requests against numbers published nowhere (reliability audit 2026-10-26, D-customer-journey Journey 3 and §3 row 12; C §8 gap G8-3). The v1 reference was live with no retirement notice and copy-paste
curlto routes that answered a text/plain 404 (row 4).Change
api-reference/v2/error-responses.mdx: a "Limits per plan" table (query, ingest, items, upload volume, context volume, monthly enrichment tokens, storage, connectors, the transport caps) at#limits-per-plan, which is the anchor the API's 413 messages link; a "what each refusal looks like" table; status rows for402(PLAN_LIMIT_REACHED,PAYMENT_REQUIRED,FREE_PLAN_DEPRECATED),403 PLAN_UNRESOLVED, the JSON404 NOT_FOUNDfor unknown paths,410 ENDPOINT_RETIRED,413as a per-request allowance,Retry-Afteron every429; the codes table and retry pattern updated to match;meta.api_versionanddetailin the envelope table.api-reference/v2/index.mdx: status rows for 402/410/413, the rate-limits paragraph points at the table and explainsRetry-After, and the "v1 endpoints remain available" line says what v1 does instead.api-reference/index.mdx,error-responses.mdx,sdks.mdx, everyapi-reference/endpoint/*.mdx): one retirement notice throughsnippets/v1-retired.mdx; the two "contact founders@ for current limits" lines point at the table.Companion
hydradb-application PR: https://github.com/hydra-db/hydradb-application/pull/2780 (PRO-2965: 402 for entitlement, 429 with Retry-After for velocity, 413 for size, 403 for an unresolved plan, JSON 404/410 for unknown and retired routes). The numbers in the table are the ones in
application/internal/ratelimit/policy.goanddomain/ingestion/models.goonstaging(Ship context volume is 20,000 words after #2617).Rollout notes
Publish together with, or after, the application PR: the table describes the refusals as that PR sends them. The v1 banner is accurate once that PR is in prod (today three v1 routes already answer 410 and three are aliased; the other sixteen still answer 404).
🤖 Generated with Claude Code
Need help on this PR? Tag
@codesmith-botwith what you need.