diff --git a/api-reference/api-keys.mdx b/api-reference/api-keys.mdx
index 2ebe9e6..0a523f0 100644
--- a/api-reference/api-keys.mdx
+++ b/api-reference/api-keys.mdx
@@ -18,6 +18,10 @@ Every request to the Pioneer API requires an API key passed in the `X-API-Key` h
 
 Generates a new API key associated with your account. The full key value is returned only once at creation time — store it securely immediately.
 
+<Note>
+  Rate limit for this endpoint is **50 requests per hour** per authenticated account.
+</Note>
+
 **Request body**
 
 <ParamField body="name" type="string" required>
diff --git a/api-reference/rate-limits.mdx b/api-reference/rate-limits.mdx
index 6a912a5..4ac468a 100644
--- a/api-reference/rate-limits.mdx
+++ b/api-reference/rate-limits.mdx
@@ -1,31 +1,37 @@
 ---
 title: "Rate Limits"
+description: "Current Pioneer API request-rate limits, credit-limit behavior, 429 headers, and guidance for requesting higher limits."
 ---
 
-## Request-rate quotas and daily spending caps for the Pioneer API, how to handle 429 errors, and how to request higher limits
+## Request-rate quotas, credit limits, and 429 handling
 
-The Pioneer API enforces two layers of rate limits: **request-rate limits** that cap how many API calls you can make per minute or hour, and a **daily spending cap** that bounds how much you can spend in a single UTC day. Exceeding either returns a `429 Too Many Requests` response.
+The Pioneer API enforces **request-rate limits** that cap how many API calls you can make per minute or hour. Exceeding a request-rate limit returns a `429 Too Many Requests` response.
+
+Credit limits and spend caps are enforced separately. If your account runs out of credits or hits a configured spend cap, the API returns `402 Payment Required`. See [Errors](/api-reference/errors#402-payment-required) for recovery steps.
 
 ## Request-rate limits
 
-A global default applies per client IP address. Per-endpoint limits apply per authenticated user and stack on top of the global default.
+A global default applies per client IP address. Authenticated endpoint limits are keyed by billing team when available, then by API key, user, or client IP. Endpoint limits stack on top of the global default.
 
 | Endpoint | Scope | Limit |
 | --- | --- | --- |
-| All endpoints (default) | Per client IP | 1,000 / min · 10,000 / hour |
-| `POST /inference` | Per user | 1,200 / min |
-| `POST /v1/chat/completions`, `/v1/completions`, `/v1/responses`, `/v1/messages` | Per user | 200 / min |
-| `POST /gliner-2/*` | Per user | 15,000 / min |
-| `POST /generate/*` | Per user | 120 / min |
-| `POST /felix/training-jobs` | Per user | 20 / min |
+| All endpoints (default) | Per client IP | 20,000 / min · 1,000,000 / hour |
+| `POST /inference` | Authenticated account | 5,000 / min |
+| `POST /v1/chat/completions`, `POST /v1/completions`, `POST /v1/responses`, `POST /v1/messages` | Authenticated account | 5,000 / min |
+| `POST /gliner-2` | Authenticated account | 15,000 / min |
+| `POST /generate` | Authenticated account + shared global | 120 / min per account · 500 / min globally |
+| `POST /felix/training-jobs` | Authenticated account | 20 / min |
+| `POST /create-api-key` | Authenticated account | 50 / hour |
 
-## Daily spending cap
+<Note>
+  The `POST /generate` scoped limit applies to starting async generation jobs. `GET /generate/jobs/:job_id` and label-existing generation routes still use the default API request-rate limits.
+</Note>
 
-If a request exceeds your remaining allowance, you'll receive a`429 Too Many Requests` response with an `X-RateLimit-Reason: daily_spend_cap_exceeded` header. You can check your current usage and remaining allowance anytime in the dashboard or via `GET /billing/usage/requests`.
+## Credit limits and spend caps
 
-Inference usage is subject to credit-based rate limits, which vary by plan and reset on a daily, monthly, or other periodic basis. Your current limits are always visible in the billing section of the dashboard.
+Inference usage is subject to credit limits and spend caps that vary by plan and reset on a daily, monthly, or other periodic basis. Your current limits are always visible in the billing section of the dashboard. You can also inspect recent usage with `GET /billing/usage/requests`.
 
-Spending caps and plan limits are subject to availability and may be adjusted over time. 
+Spending caps and plan limits are subject to availability and may be adjusted over time.
 
 <Tip>
   Need a higher limit? Reach out to [support@fastino.ai](mailto:support@fastino.ai) or your account contact and we can raise the cap on a custom plan.
@@ -33,15 +39,19 @@ Spending caps and plan limits are subject to availability and may be adjusted ov
 
 ## Handling 429 responses
 
-When you exceed a limit, the API returns `429 Too Many Requests` and includes a `Retry-After` header that tells you how many seconds to wait before retrying.
+When you exceed a request-rate limit, the API returns `429 Too Many Requests` and includes a `Retry-After` header that tells you how many seconds to wait before retrying. Rate-limit responses may also include `X-RateLimit-Scope`, `X-RateLimit-Code`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.
 
 ```bash cURL
 HTTP/2 429
 retry-after: 3
+x-ratelimit-scope: request-rate
+x-ratelimit-code: rate_limited
 content-type: application/json
 
 {
-  "detail": "Rate limit exceeded: ..."
+  "detail": "Rate limit exceeded: ...",
+  "code": "rate_limited",
+  "scope": "request-rate"
 }
 ```
 
@@ -68,11 +78,11 @@ def call_with_retry(url, headers, payload, max_retries=5):
 ```
 
 <Note>
-  Spending-cap 429s won't resolve by waiting — they clear at 00:00 UTC. The retry loop above raises immediately instead of sleeping when `daily_spend_cap_exceeded` is set.
+  Credit-limit and spend-cap errors return `402 Payment Required`, not `429`. Retrying a `402` will not help until you add credits, change billing settings, or wait for the relevant reset.
 </Note>
 
 ## Requesting higher limits
 
-If the default or Pro-tier limits don't fit your workload, contact the Pioneer team to discuss a custom plan.
+If the default limits don't fit your workload, contact the Pioneer team to discuss a custom plan.
 
-[Request higher limits](https://forms.gle/uzRf8bM2yZtpJFmd7)
\ No newline at end of file
+[Request higher limits](https://forms.gle/uzRf8bM2yZtpJFmd7)
diff --git a/api-reference/synthetic-data.mdx b/api-reference/synthetic-data.mdx
index 963f640..c448fdc 100644
--- a/api-reference/synthetic-data.mdx
+++ b/api-reference/synthetic-data.mdx
@@ -7,7 +7,7 @@ description: "Start Pioneer data generation jobs for NER, classification, or dec
 Pioneer's data generation API lets you produce high-quality labeled training examples without manually annotating data. You can generate synthetic examples from scratch for NER, classification, and decoder tasks, or bring your own unlabeled text and have Pioneer label it automatically. All generated data is saved directly to a named dataset ready for fine-tuning.
 
 <Note>
-  Generate endpoints are rate-limited to **120 requests per minute** per user. For large datasets, consider batching your requests or using the job polling endpoint to monitor long-running generation jobs.
+  `POST /generate` is rate-limited to **120 requests per minute** per authenticated account and **500 requests per minute** globally. Other generation routes use the default API request-rate limits. For large datasets, request larger batches and poll the job status endpoint instead of starting many small jobs.
 </Note>
 
 ---
diff --git a/api-reference/training-jobs.mdx b/api-reference/training-jobs.mdx
index 7198b30..7f878db 100644
--- a/api-reference/training-jobs.mdx
+++ b/api-reference/training-jobs.mdx
@@ -32,7 +32,7 @@ Training jobs are the core of Pioneer's fine-tuning platform. You submit a job w
 Submits a new fine-tuning job. Returns immediately with a job ID and `requested` status — use `GET /felix/training-jobs/:id` to poll for progress.
 
 <Note>
-  Rate limit for this endpoint is **20 requests per minute** per user.
+  Rate limit for this endpoint is **20 requests per minute** per authenticated account.
 </Note>
 
 **Request body**
@@ -361,4 +361,4 @@ curl https://api.pioneer.ai/felix/trained-models \
 
 <Note>
   **Data Privacy:** If you would like to opt out of having your data used in Fastino's model training, please email [support@fastino.ai](mailto:support@fastino.ai) and we will ensure your data is excluded from our training pipelines.
-</Note>
\ No newline at end of file
+</Note>
diff --git a/guides/synthetic-data.mdx b/guides/synthetic-data.mdx
index 85ccfcb..1bb91e1 100644
--- a/guides/synthetic-data.mdx
+++ b/guides/synthetic-data.mdx
@@ -170,7 +170,7 @@ curl -X POST https://api.pioneer.ai/generate/classification/label-existing \
 Both endpoints accept 1–1,000 strings per request and return annotations synchronously. Required fields are `labels` and `inputs`.
 
 <Warning>
-  Generation endpoints are rate-limited to 120 requests per minute per user. For large annotation jobs, batch your inputs and add a short delay between requests. If you need higher throughput, contact the Pioneer team about an enterprise plan.
+  `POST /generate` is rate-limited to 120 requests per minute per authenticated account and 500 requests per minute globally. Label-existing routes use the default API request-rate limits. For large annotation jobs, batch your inputs and add retry backoff. If you need higher throughput, contact the Pioneer team about an enterprise plan.
 </Warning>
 
 ## Next steps