sunnybhara · mintlify · Apr 19, 2026
diff --git a/api-reference/rubric-classify.mdx b/api-reference/rubric-classify.mdx
@@ -101,7 +101,9 @@ result = nawa.rubric.classify(
     "dialect_confidence": 0.91,
     "language": "ar",
     "model": "nagl-v1",
-    "cached": false
+    "cached": false,
+    "cost_usd": 0.003,
+    "credits_used": 3
   },
   "errors": [],
   "request_id": "req_rub123abc456"
@@ -113,9 +115,11 @@ result = nawa.rubric.classify(
 | Field | Type | Description |
 |-------|------|-------------|
 | `category` | string | The top matching category from your rubric |
-| `category_confidence` | number | Confidence score (0–1) for the top category |
+| `category_confidence` | number | Confidence score (0-1) for the top category |
 | `scores` | object | Confidence scores for all rubric categories |
 | `dialect` | string | Detected Arabic dialect |
-| `dialect_confidence` | number | Dialect confidence score (0–1) |
+| `dialect_confidence` | number | Dialect confidence score (0-1) |
 | `language` | string | Detected language code |
 | `cached` | boolean | Whether served from semantic cache |
+| `cost_usd` | number | Cost in USD. Always `0.003` for this endpoint. |
+| `credits_used` | integer | Credits deducted. Always `3` for this endpoint. |
diff --git a/authentication.mdx b/authentication.mdx
@@ -22,7 +22,7 @@ Authorization: Bearer nawa_live_sk_xxx
 <CardGroup cols={2}>
   <Card title="Free" icon="flask">
     **Free, no credit card required.**
-    - 100 lifetime requests
+    - 100 lifetime requests per account (not per key -- creating new free keys does not reset the counter)
     - 14-day key expiry
     - Uses real AI models (same accuracy)
     - Rate limit: 10 requests/minute

diff --git a/billing.mdx b/billing.mdx
@@ -16,13 +16,13 @@ NAWA uses a prepaid credit system.
 
 <CardGroup cols={1}>
   <Card title="Free tier" icon="flask">
-    - **100 lifetime requests** per free key (`nawa_test_sk_`)
+    - **100 lifetime requests** per account (`nawa_test_sk_`). The cap is per user, not per key -- creating new free keys does not reset it.
     - 14-day key expiry
     - No credit card required
     - Uses real AI models -- same accuracy as paid
     - Rate limit: 10 requests/minute
     - Free endpoints (health, usage, analytics, comments, feedback) do not count toward the 100 limit
-    - When exhausted: create a new free key or purchase credits for a live key
+    - When exhausted: purchase credits for a live key
   </Card>
 </CardGroup>
 
@@ -114,7 +114,7 @@ Refunds for unused credits are processed to the original payment method within 5
 
 <AccordionGroup>
   <Accordion title="Do free key requests consume my paid credits?">
-    No. Free keys (`nawa_test_sk_`) have their own pool of 100 lifetime requests. Paid credits are only consumed by live keys (`nawa_live_sk_`).
+    No. Free keys (`nawa_test_sk_`) have their own pool of 100 lifetime requests per account. Paid credits are only consumed by live keys (`nawa_live_sk_`).
   </Accordion>
   <Accordion title="Do credits expire?">
     No. Credits never expire. Use them at your own pace.

diff --git a/errors.mdx b/errors.mdx
@@ -181,15 +181,25 @@ Your account balance is insufficient for the requested operation.
 
 <AccordionGroup>
   <Accordion title="balance_exhausted">
-    **Cause:** Your credit balance has reached $0. There is no grace period -- paid endpoints stop immediately.
+    **Cause:** Your credit balance is too low for the requested operation. There is no grace period -- paid endpoints stop immediately when credits are insufficient.
 
     **Fix:** Purchase a credit pack from the dashboard to restore access instantly.
 
+    The error object includes two additional fields to help you handle this programmatically:
+
+    | Field | Type | Description |
+    |-------|------|-------------|
+    | `balance_credits` | integer | Your current credit balance |
+    | `required_credits` | integer | Credits needed for this request |
+
     ```json
     {
       "type": "insufficient_credits",
       "code": "balance_exhausted",
-      "message": "Credit balance exhausted. Purchase credits to continue.",
+      "message": "Insufficient credits. Balance: 2, required: 6.",
+      "display_message": "Your credit balance is too low for this request.",
+      "balance_credits": 2,
+      "required_credits": 6,
       "suggested_action": "Buy a credit pack at trynawa.com/developers/keys."
     }
     ```

diff --git a/openapi.yaml b/openapi.yaml
@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: NAWA API
-  version: 1.1.1
+  version: 1.2.0
   description: |
     Arabic language intelligence API.
     تصنيف ذكي للمحتوى العربي  -  من الخليج إلى المغرب.
@@ -573,6 +573,8 @@ paths:
                       language: ar
                       model: nagl-v1
                       cached: false
+                      cost_usd: 0.003
+                      credits_used: 3
                     errors: []
                     request_id: req_rub123abc456
         "400":
@@ -1206,25 +1208,25 @@ paths:
         - name: from
           in: query
           required: false
+          description: "Start date (ISO 8601). Default: start of current month."
           schema:
             type: string
             format: date-time
-          description: Start date (ISO 8601). Default: start of current month.
         - name: to
           in: query
           required: false
+          description: "End date (ISO 8601). Default: now."
           schema:
             type: string
             format: date-time
-          description: End date (ISO 8601). Default: now.
         - name: group_by
           in: query
           required: false
+          description: Group results by time period or endpoint
           schema:
             type: string
             enum: [day, week, month, endpoint]
             default: day
-          description: Group results by time period or endpoint
       responses:
         "200":
           description: Usage statistics
@@ -1380,7 +1382,7 @@ components:
       description: AI provider used for this request
       schema:
         type: string
-        enum: [allam, claude]
+        enum: [allam, claude, gemini]
     X-NAWA-Cache:
       description: Whether the response was served from semantic cache
       schema:
@@ -1973,6 +1975,12 @@ components:
           type: string
         cached:
           type: boolean
+        cost_usd:
+          type: number
+          description: Cost in USD. Always 0.003 for this endpoint.
+        credits_used:
+          type: integer
+          description: Credits deducted. Always 3 for this endpoint.
 
     ReplyResult:
       type: object
@@ -2262,6 +2270,7 @@ components:
                 - invalid_request_error
                 - not_found_error
                 - api_error
+                - insufficient_credits
             code:
               type: string
             message:
@@ -2325,13 +2334,15 @@ components:
           example:
             type: error
             error:
-              type: permission_error
-              code: insufficient_credits
-              message: Credit balance is $0.00
-              display_message: Your account has insufficient credits.
+              type: insufficient_credits
+              code: balance_exhausted
+              message: "Insufficient credits. Balance: 2, required: 6."
+              display_message: Your credit balance is too low for this request.
               param: null
               doc_url: https://developers.trynawa.com/billing
-              suggested_action: Purchase credits at trynawa.com/developers/keys.
+              suggested_action: Buy a credit pack at trynawa.com/developers/keys.
+              balance_credits: 2
+              required_credits: 6
             request_id: req_nw_a1b2c3d4e5f67890
 
     RateLimited:

diff --git a/rate-limits.mdx b/rate-limits.mdx
@@ -11,12 +11,13 @@ NAWA enforces per-minute rate limits on each API key to ensure fair usage and pl
 | Tier | Requests/min | How you get it |
 |------|-------------|----------------|
 | **Free** | 10 | Free keys (`nawa_test_sk_`) |
+| **Trial** | 60 | Live keys on the trial plan |
 | **Growth** | 120 | Live keys (`nawa_live_sk_`) with credits |
 | **Enterprise** | 300 | Contact [sales@trynawa.com](mailto:sales@trynawa.com) |
 | **Enterprise+** | 1,000 | Contact [sales@trynawa.com](mailto:sales@trynawa.com) |
 
 <Note>
-  Free keys are rate-limited to 10 requests/minute and have a hard cap of 100 lifetime requests. Live keys start at the Growth tier (120/min). Enterprise tiers are available on request -- contact [sales@trynawa.com](mailto:sales@trynawa.com).
+  Free keys are rate-limited to 10 requests/minute and have a hard cap of 100 lifetime requests per account (not per key -- creating new free keys does not reset the counter). Live keys start at the Growth tier (120/min). Enterprise tiers are available on request -- contact [sales@trynawa.com](mailto:sales@trynawa.com).
 </Note>
 
 ## Rate limit headers