API rate-limit localization is systems localization. A message such as “100 requests per minute”, “10,000 requests remaining”, “quota resets at 00:00 UTC”, “retry after 30 seconds” or “429 Too Many Requests” is not flexible marketing copy. It describes a machine-enforced boundary. If the target language changes the unit, scope, window, remaining count, reset moment or retry instruction, developers can write code that behaves incorrectly even though the sentence sounds fluent.
Searches for API rate limit localization, API quota translation, usage dashboard localization, 429 Too Many Requests translation, Retry-After localization, developer portal localization, API usage limits and multilingual API documentation all point to the same principle: translate the explanation, never rewrite the enforcement model. A request limit can be per user, token, application, organisation, IP address or endpoint; a quota can renew hourly, daily, monthly or at a billing-cycle boundary; and a burst limit can be exhausted even while a longer-term quota remains available.
This guide explains how to localize API rate limits, quotas, usage dashboards and limit errors without changing thresholds, windows or enforcement. It covers fixed and rolling windows, token-bucket concepts, concurrency limits, payload limits, request counts, reset times, HTTP 429, Retry-After, response headers, primary and secondary limits, billing allowances, GraphQL or point-based cost models, dashboard progress, warning thresholds, code examples, SDK errors, time zones, accessibility, analytics and the release tests that prove target-language guidance still matches the live API.
This article belongs to eduKateSG’s Master Art of Translation architecture. It connects to the existing API and SDK documentation localization guide, but owns a narrower operational boundary: how a multilingual product explains capacity, throttling, exhaustion, reset and retry without changing what the server will actually enforce.
Quick answer
Keep limits as structured policy. Threshold, unit, subject, resource, window, reset time, remaining amount, burst allowance, error code and retry instruction should come from machine-readable configuration or response data wherever possible. Localize labels, prose, number presentation and help text around those values. Never translate a stable HTTP header name, endpoint, field, code token or machine identifier. If developers reading the target language would implement a different retry strategy from developers reading the source, the localization has changed the API contract.
1. Separate rate limits from quotas before translating either one
A rate limit controls how quickly requests can be made. A quota controls how much can be consumed over a broader period or allocation. They can overlap, but they answer different questions. “60 requests per minute” is a rate. “One million requests per month” is a quota. A user can remain far below the monthly quota and still hit the minute-by-minute rate limit.
Many interfaces use “limit” as a generic umbrella, so localization teams need the product model rather than the English word alone. If the target language has separate natural terms for speed, allowance and ceiling, use them consistently. If one term must cover several concepts, add the window or resource explicitly so the reader can still tell what is constrained.
A useful terminology table includes limit type, counted unit, scope, window, enforcement behavior and recovery condition. Translators can then distinguish a request rate, storage quota, token budget, concurrent-connection limit, file-size maximum and monthly billing allowance even when the source UI uses the same noun.
2. Every limit needs a subject: who or what is being limited?
“1,000 requests per hour” is incomplete unless the reader knows whether the limit applies per API key, per user, per organisation, per IP address, per project or across the entire account. Translating the numerical phrase perfectly while losing its scope can cause application architects to make the wrong assumptions.
Make scope a structured field where possible. A dashboard can say “Organisation limit”, “Per-user limit” or “Per-token limit” while the backend attaches usage to a stable subject ID. If several limits apply simultaneously, explain which one is currently constraining the request.
Test shared credentials and multi-tenant applications. A developer may assume every end user receives the full allowance when the server actually counts all traffic under one application token. Localized documentation should not accidentally reinforce that false model through vague pronouns such as “your limit”.
3. The counted resource matters as much as the number
One endpoint may count each HTTP request equally. Another platform may charge points according to query complexity, tokens generated, bytes transferred, records processed or compute time. A limit of “5,000 per hour” is meaningless without the counted unit.
Translate human-readable unit labels while keeping machine field names stable. If the API exposes `remaining`, `cost`, `points` or another field, the documentation can explain it in the target language without renaming the JSON key. A developer should be able to copy code from the target-language documentation and still call the API correctly.
For point-based systems, show examples. A simple query might cost one point while a complex query costs many. Do not translate “request” as if every request costs exactly one unit unless the policy actually works that way.
4. Fixed windows, rolling windows and token buckets imply different behavior
Two products can both say “60 requests per minute” while enforcing that phrase differently. A fixed window may reset at a boundary. A rolling window may consider the preceding 60 seconds. A token-bucket model may refill gradually and permit bursts. Localization should preserve the mechanism when documentation exposes it.
Do not simplify “rolling 60-second window” to “resets every minute” unless the behavior really resets on minute boundaries. That rewrite can encourage clients to burst at the wrong time. Likewise, “tokens refill continuously” is not the same as “the allowance resets at the top of the hour”.
When the product does not promise an algorithm, avoid inventing one. Translate the guaranteed behavior—limit, headers, errors and retry guidance—without speculating about internal implementation. Developer trust depends on distinguishing contract from explanation.
5. Burst limits should not be confused with sustained limits
APIs often allow short bursts while limiting sustained traffic. A customer can therefore hit a short-term throttle even with low average usage. The target documentation should explain both dimensions if the service publishes them. “100 requests per second, up to 1,000 burst capacity” is different from a flat 1,000 requests per second.
Use target-language terms that preserve short-term capacity versus long-term rate. If the word “burst” has no natural technical equivalent, explain it rather than substituting a generic “maximum”. A maximum can sound absolute when the system actually describes temporary accumulated capacity.
Dashboard progress bars should not combine burst and sustained limits into one percentage unless the product deliberately models them that way. Separate indicators help developers understand why a request was throttled while the longer-term quota still looks healthy.
6. Concurrency limits are not request-rate limits
A concurrency limit controls how many operations can be active at once. A client can make few requests per second and still exceed concurrency if requests take a long time. Translating “10 concurrent requests” as “10 requests per second” changes the contract.
Explain what counts as active: open connections, in-flight jobs, running exports, streaming requests or background tasks. If queued work does not count, say so. If long-lived streams consume slots, show that example. The target language should let a developer design the correct scheduler.
When the same account has rate, quota and concurrency limits, present them as separate constraints. A single label such as “usage limit” may be too vague for troubleshooting.
7. Payload and object-size limits need units that cannot drift
Maximum request body, upload size, batch size, field length and response size are another family of limits. Translators must preserve both value and unit. MB and MiB are not automatically the same. Characters, bytes and Unicode code points are not interchangeable measures of text length.
Keep technical unit symbols stable when the specification uses them. Localize explanatory prose and number formatting only when that cannot be confused with the machine contract. If an endpoint accepts 100 items per batch, do not replace “items” with “records” unless the API documentation treats those nouns as equivalent.
Boundary tests should send exactly the maximum, one below and one above. Compare target-language error messages with actual server behavior. This catches a surprisingly common problem: documentation says one number while configuration enforces another.
8. Remaining, used and total are three different quantities
A usage dashboard can show “8,000 of 10,000 used” or “2,000 remaining”. These are mathematically related but not linguistically interchangeable. Progress bars also need a clear direction. Does 80% mean used or remaining? A mistranslated label can make a healthy account look almost exhausted or the reverse.
Bind labels to field semantics. `limit` is the ceiling, `used` is consumption and `remaining` is unused allowance. If usage data is delayed, add a freshness indicator rather than implying real-time precision. If the server’s response headers are authoritative while the dashboard updates every few minutes, explain that difference.
Test zero and full states. “0 remaining” must not become “0 used”. “Unlimited” should appear only when no relevant ceiling applies; a very high number is not the same as unlimited.
9. Reset time is an instant, not a phrase to rewrite manually
Rate-limit and quota interfaces often show when capacity resets. Store a canonical timestamp or server-provided value and render it in the user’s locale. If the API reports an epoch value or UTC timestamp, the documentation should preserve that machine meaning while the UI can add a human-readable local time.
“Resets in 12 minutes” is a duration. “Resets at 14:00 UTC” is an instant. They should agree, but they are different representations. Do not manually translate a clock time into a new time zone inside static documentation. Generate it when the product has live state.
Test reset displays around midnight, daylight-saving transitions and locale date boundaries. A developer in Singapore and a developer in California may see different local dates for the same reset event, but the underlying instant must be identical.
10. HTTP 429 must remain HTTP 429
RFC 6585 defines the HTTP 429 status code for Too Many Requests. The reason phrase can be explained in any language, but the numeric status code is stable. Do not replace it with a local number, translate it into another code or hide it behind only a friendly message.
Documentation should tell developers what condition caused the response according to the service’s actual policy. A 429 can represent a primary rate limit, secondary throttle or another request-frequency restriction. Some services may also use other status codes in limit-related situations. Describe the specific API rather than assuming every platform behaves identically.
Error examples should preserve JSON field names, status code, header names and request IDs. Translate human messages and commentary around them. This lets a developer compare the target-language page with logs, SDK exceptions and network traces.
11. Retry-After is machine guidance, not an invitation to guess
An HTTP response can include a `Retry-After` header telling the client when to try again. RFC 6585 notes that a 429 response may include it. If the server supplies a retry interval or time, the localized documentation should teach clients to respect that value rather than inventing a translated fixed delay.
Keep the header name `Retry-After` unchanged. Translate its explanation. If the API recommends exponential backoff when no explicit retry time is available, preserve the algorithm and any limits exactly. “Wait a little and retry” is too vague for production code.
GitHub’s REST API documentation, for example, tells clients to inspect response information such as `retry-after` and rate-limit reset details depending on the situation. The general lesson is to follow the live service signal. The target-language page should not create a second, contradictory retry policy.
12. Header names and JSON fields should not be translated
APIs expose rate-limit information through HTTP headers or response fields. Names such as `Retry-After`, `X-RateLimit-Remaining`, `x-ratelimit-reset` or vendor-specific JSON keys are machine interfaces. Preserve the exact spelling and case conventions shown by the API. Localize the descriptive table around them.
A translated table can have columns such as “Field”, “Meaning” and “Example”. The field token remains exact while the meaning is translated. This pattern keeps documentation readable without making copy-and-paste code fail.
If the platform migrates from legacy headers to standardised fields, version the documentation. Do not silently translate old and new mechanisms into one phrase that hides which API version supports which signal.
13. Primary and secondary limits need separate explanations
Some APIs enforce a published primary limit and additional secondary or abuse-prevention limits. A client can remain below the main hourly quota and still be throttled because of request patterns, expensive endpoints or excessive concurrency. Translating every throttle as “quota exceeded” is therefore misleading.
Use the terminology published by the service and preserve uncertainty when the exact secondary threshold is intentionally not documented. If the provider says limits can vary, do not turn that into a fixed number. Developer guidance should focus on respectful request patterns, retry behavior and response signals.
Dashboard design can show the primary allowance without implying that staying below it guarantees every request will succeed. A short explanatory note can prevent users from treating one visible meter as the entire enforcement system.
14. Technical limits and commercial entitlements are different layers
A plan may include ten million requests per month while the API also enforces 100 requests per second. The monthly figure is a commercial or billing allowance; the per-second figure protects service operation. Upgrading the plan may change one, both or neither.
Translate “included usage”, “overage”, “quota”, “rate limit” and “throttling” as distinct concepts if the product distinguishes them. A developer should not believe paying for a larger monthly allowance automatically increases concurrency or burst capacity.
Pricing pages, developer docs and usage dashboards must agree. If one locale says “unlimited requests” while technical documentation describes a protective rate limit, the phrase “unlimited” needs qualification. Commercial messaging cannot erase operational constraints.
15. Warning thresholds should not masquerade as enforcement thresholds
A dashboard may warn at 70%, 80% or 90% of quota. Those alerts are advisory; the actual limit might be 100%. Translating “warning threshold” as “limit” can make users believe requests will stop earlier than they do. Conversely, a soft warning should not sound optional if it predicts imminent exhaustion of a critical resource.
Keep warning configuration separate from server enforcement. If users can choose an alert at 75%, localize the control as an alert threshold. If the provider enforces a hard limit at 100%, label that separately. A progress bar can show both markers when design permits.
Forecasts such as “estimated to exceed quota in three days” should preserve their probabilistic status. They are predictions based on recent consumption, not guaranteed reset or exhaustion times. Translate “estimated” with the same uncertainty as the source.
16. Usage dashboards should reveal freshness and scope
Usage numbers may be real-time, near-real-time or delayed. A developer investigating a 429 response can become confused if the dashboard still shows capacity because data is ten minutes old. Localize “last updated”, “data delayed” and “estimated usage” clearly.
Dashboard filters should show which project, token, endpoint, region or organisation is being measured. “42% used” is meaningless without context. Keep underlying filter IDs stable and localize display names. If the same API key spans several environments, clarify whether usage combines them.
Charts should preserve units and aggregation periods. Requests per minute, daily total requests and peak concurrency are different metrics even if all are drawn as lines. Localize chart titles and legends from structured metric metadata rather than hand-written labels.
17. Point-based and GraphQL limits need cost language
Some APIs do not count every operation equally. GraphQL services may assign points to queries, while AI services can meter tokens, characters, images or compute units. The localization should teach the cost model, not convert everything back into “requests”.
Use examples that show how one operation consumes more units than another. Preserve formulas, variable names and code syntax. If a dashboard shows “points remaining”, do not translate the label as “requests remaining” simply because users are accustomed to request counts.
Where cost is estimated before execution and final usage is known afterward, distinguish those states. “Estimated cost” is not “charged cost”. This matters for planning large batches and for reconciling dashboard totals.
18. Batch endpoints can change how limits are consumed
An endpoint that accepts 100 records in one request may count as one request, 100 operations or a weighted cost depending on the API. Localized documentation should state the counting rule. Otherwise developers may batch aggressively and discover that usage does not fall as expected.
Batch-size limits and rate limits are separate. “Maximum 100 items per batch” does not mean “100 items per minute”. Keep the nouns, units and windows explicit. If partial failures inside a batch still consume quota, mention that behavior where the API guarantees it.
Code examples should log both response status and any returned limit metadata. That lets developers in any locale diagnose how a batch affects consumption rather than relying on prose alone.
19. SDK errors should preserve machine causes while adding readable help
An SDK may wrap HTTP 429 in a language-specific exception. Localize documentation and human error descriptions, but keep exception class names, properties and code samples exact. A developer searching Stack Overflow, GitHub issues or logs needs the real symbol.
Good documentation shows the machine cause, the human meaning and the recommended response. For example: HTTP 429, rate limit exceeded for a specific scope, inspect reset or retry information, then retry safely. Do not replace the concrete status with only “Please try later”.
When several SDKs have different names for the same server error, keep each language’s symbol unchanged and translate the explanation consistently. Localization should connect code to concept, not rewrite code into natural language.
20. Code examples should remain executable after localization
Developer documentation often places explanatory comments beside code. Translate comments where useful, but do not translate programming-language keywords, endpoint paths, header names, environment-variable names or JSON keys. A code block should still run after the surrounding page is localized.
Be careful with decimal separators and quotation marks. Smart punctuation can break shell commands or JSON. Localized digits may be appropriate in narrative text but not inside machine values expected by code. The safest pattern keeps executable blocks byte-stable unless the example intentionally demonstrates localizable data.
Automated documentation tests can compile or execute examples from every language version. This catches a class of localization error that human linguistic review often misses.
21. Numbers can be localized visually without changing values
A dashboard may display 10,000 as 10 000, 10.000 or another locale convention. That is presentation. The underlying integer remains ten thousand. Distinguish display formatting from machine syntax in documentation, especially when readers copy values into configuration files.
Percentages, decimals and durations need similar care. “0.5 seconds” should not become “0,5” inside JSON if the parser expects a period, even if narrative text uses a comma. Put machine examples in code formatting and use locale-aware formatting in ordinary prose.
Do not round values that drive behavior. A dashboard may round 99.6% to 100% for a chart, but a textual remaining count can still show capacity. If rounding is used, label it or choose a precision that does not imply an impossible state.
22. Error messages should say what was limited and what to do next
“Rate limit exceeded” is better than a generic “Request failed”, but a useful message can often go further: which scope was exhausted, when capacity returns, whether retry is safe and where usage can be viewed. The target language should preserve each available fact.
Do not promise that a retry will succeed if another limit could still apply. “Retry after 30 seconds” means the client should wait at least according to the service’s instruction; it does not necessarily guarantee that every other condition will be satisfied. Preserve this boundary between guidance and guarantee.
Support references and request IDs should remain exact. If a user contacts support about throttling, the same identifier should connect localized UI, logs and backend traces.
23. Accessibility matters because usage dashboards are visual by default
Quota dashboards often use colored meters: green for healthy, amber for warning and red for exhausted. Do not rely on color. Include remaining amount, percentage and state in text that screen readers can access. Translate those labels with the same controlled terminology used elsewhere.
Charts need accessible summaries. A user should be able to learn that usage climbed from 20% to 80% over seven days without interpreting a line visually. Reset times and warning markers should also be announced in a logical reading order.
Right-to-left interfaces need special testing around code, header names, timestamps and mathematical expressions. Bidirectional isolation keeps technical tokens from appearing reordered. Copy buttons should return the actual machine string, not the visually rearranged presentation.
24. Live telemetry should outrank stale translated documentation
Limits can vary by plan, endpoint, authentication method or account. When the service exposes current limit and remaining values in responses, those signals should be treated as authoritative for runtime behavior. Documentation explains the policy but should not override the server.
A localized page that hard-codes “5,000 requests per hour” can become stale after a product change. Where possible, generate plan-specific values from configuration or clearly version the page. When a value is only an example, label it as an example in every locale.
Release processes should compare public documentation, dashboard configuration and real response headers. Localization is part of this consistency check because translated static values can lag behind even when the source page is updated.
25. Boundary testing proves the translation matches enforcement
Test below, at and above each important boundary. If the limit is 100 requests, send 99, 100 and 101 under the documented counting rule. If the window resets at a known time, test immediately before and after. If concurrency is ten, hold ten operations open and attempt an eleventh.
Compare what the server does with what the target-language page says. Record status code, headers, response body, dashboard state and reset time. A mismatch is either a product defect, documentation defect or localization defect; users experience all three simply as the API being unreliable.
Repeat with every priority locale where dynamic number and time rendering changes. The values should remain semantically identical. Only presentation should differ.
A repeatable localization sequence
- Inventory every rate, quota, concurrency, payload and commercial-usage limit.
- Record subject, resource, unit, threshold, window and recovery condition for each limit.
- Separate machine tokens from human-readable labels.
- Generate remaining values and reset times from live structured data wherever possible.
- Keep HTTP codes, headers, JSON keys, endpoints and code symbols unchanged.
- Distinguish primary, secondary, burst and concurrency constraints.
- Separate billing allowance from technical throttling.
- Test 429 and retry guidance against actual response behavior.
- Verify dashboards for scope, freshness and accessible meaning.
- Run boundary tests before every major limit or plan change.
Sixteen professional practice cases
Case 1: 60 requests per minute per token
The target copy must preserve all four elements: 60, requests, one-minute window and per-token scope. Omitting the subject can make teams assume every user receives a separate allowance.
Case 2: Monthly quota remains, but the burst limit is exhausted
Explain why requests are temporarily throttled even though the dashboard shows unused monthly allowance. Do not label the event as monthly quota exhaustion.
Case 3: The server returns HTTP 429
Keep 429 unchanged, translate the human explanation and preserve any response headers or request ID. The user should be able to match the localized documentation to the network trace.
Case 4: Retry-After is 30 seconds
Teach the client to respect the server-provided value. Do not replace it with a translated hard-coded “one minute” delay simply because the prose template previously used that example.
Case 5: A limit resets at 00:00 UTC
Display local time if useful, but preserve the same instant. A user in another time zone may see a different calendar date. The policy does not move with the viewer.
Case 6: A concurrency limit is ten active jobs
Do not translate this as ten jobs per second. Explain that the eleventh job must wait until an active slot becomes free if that is the service behavior.
Case 7: A batch can contain 100 records
Keep batch size separate from request rate. If one batch consumes multiple quota units, document that counting rule explicitly.
Case 8: The dashboard is ten minutes behind
Show a freshness indicator. A developer who just hit a throttle should not assume the server is wrong because the delayed chart still shows remaining capacity.
Case 9: The plan includes one million requests per month
Do not call this unlimited. If separate per-second throttles apply, surface them in technical documentation and avoid commercial wording that implies no operational limits exist.
Case 10: A GraphQL query costs 25 points
Translate “points” as the service’s cost unit, not “25 requests”. Preserve formulas and machine fields used to calculate or report cost.
Case 11: A secondary limit triggers
Do not claim the primary hourly quota is exhausted if it is not. Explain the secondary-throttling condition only to the degree the provider documents it and follow the response’s retry guidance.
Case 12: Remaining equals zero
Make the direction explicit. A progress bar labeled “0” without “remaining” or “used” is ambiguous. Show reset or recovery information when available.
Case 13: The docs show a code sample reading a header
Translate the explanation, not the header key or programming syntax. Run the localized example through tests to confirm it remains executable.
Case 14: A warning fires at 80%
Call it a warning or alert threshold, not the hard enforcement limit. Users should understand that the alert gives time to react before exhaustion.
Case 15: Maximum request body is 10 MiB
Preserve the exact unit. Do not casually rewrite MiB as MB. Test payloads around the boundary and make sure the localized error cites the same limit the server enforces.
Case 16: A user changes dashboard locale mid-session
Number punctuation, labels and local reset display may change. Remaining usage, canonical reset instant, account scope and policy must not.
Release checklist
Before release, verify limit type, subject, resource, counted unit, threshold, window model, burst capacity, concurrency, payload size, used versus remaining direction, reset instant, HTTP status, retry instructions, stable header names, secondary-limit language, plan entitlement, warning thresholds, dashboard freshness, point or token cost, batch counting, SDK symbols, code executability, number presentation, accessible charts, live telemetry and boundary behavior. A translated developer experience should lead to the same client logic as the source documentation.
Frequently asked questions
What is the difference between a rate limit and a quota?
A rate limit controls request pace over a window; a quota usually controls total consumption over a broader allowance. A service can enforce both at the same time.
Should HTTP 429 be translated?
No. Keep the status code 429 unchanged. Translate the human explanation of Too Many Requests and the service-specific guidance around it.
Should Retry-After be translated?
Keep the header name `Retry-After` unchanged. Translate what it means and how clients should use the returned value.
Can reset time be shown in the user’s local time zone?
Yes, if it is rendered from the same canonical instant and the time zone is clear. The underlying reset event must not move.
Are “remaining” and “used” interchangeable?
No. They move in opposite directions. Bind each localized label to the correct structured field and test zero and full states.
Should API header names and JSON keys be translated?
No when they are part of the machine interface. Translate surrounding documentation and table labels while preserving exact tokens developers must send or read.
Can a user hit a limit while the dashboard still shows quota remaining?
Yes. The user may hit a different constraint such as a burst, concurrency or secondary limit, or the dashboard may be delayed. The product should explain which condition applied.
How do we test rate-limit localization?
Run requests around real boundaries, capture status codes and headers, compare dashboard values and reset times, and verify that target-language documentation describes the same enforcement behavior.
Selected references and next routes
- RFC 6585: Additional HTTP Status Codes, including 429 Too Many Requests
- RFC 9333: RateLimit Fields for HTTP
- GitHub Docs: Rate limits for the REST API
- eduKateSG: Localize API and SDK Documentation
Conclusion
A rate limit is a contract between software and capacity. It says who may consume what, how quickly, over which window and what happens when the boundary is reached. Translation succeeds only when every one of those dimensions survives intact.
Structured limit data, stable machine tokens, precise scope language, canonical reset time, faithful 429 and retry guidance, clear dashboard semantics and real boundary testing let multilingual API documentation remain operationally trustworthy. The goal is not merely that developers understand the words. It is that they write the same correct client behavior regardless of which supported language they read.