docs: update error contract to { error, code } matching API changes

Author: ph33nx

AGENTS.md

@@ -85,21 +85,34 @@ const { data } = await roxy.crystals.searchCrystals({
 
 ### Error handling
 
+All errors return `{ error: string, code: string }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable (stable, safe to switch on).
+
 ```typescript
 const { data, error, response } = await roxy.astrology.getDailyHoroscope({
   path: { sign: 'aries' },
 });
 
 if (error) {
-  // error is { error: string } on 4xx/5xx
-  console.error('Status:', response?.status, 'Error:', error);
+  // error is { error: string, code: string } on 4xx/5xx
+  console.error('Code:', error.code, 'Message:', error.error);
   return;
 }
 // data is fully typed after error check
 console.log(data.sign, data.overview);
 ```
 
-Common error codes: `401` invalid/missing API key, `403` subscription expired or limit reached, `429` rate limited, `404` resource not found.
+Error codes:
+
+| Status | Code | When |
+|--------|------|------|
+| 400 | `validation_error` | Missing or invalid parameters |
+| 401 | `api_key_required` | No API key provided |
+| 401 | `invalid_api_key` | Key format invalid or tampered |
+| 401 | `subscription_not_found` | Key references non-existent subscription |
+| 401 | `subscription_inactive` | Subscription cancelled, expired, or suspended |
+| 404 | `not_found` | Resource not found |
+| 429 | `rate_limit_exceeded` | Monthly quota reached |
+| 500 | `internal_error` | Server error |
 
 ## Common tasks
 
@@ -142,6 +155,7 @@ const city = cities[0];
 - **Date format is `YYYY-MM-DD`, time is `HH:MM:SS`.** Both are strings. Timezone is optional (IANA format like `America/New_York`).
 - **All list endpoints may return paginated objects** (e.g. `{ items: [...], total: N }`) rather than raw arrays. Check the type.
 - **`data` and `error` are mutually exclusive.** If `error` is set, `data` is `undefined` and vice versa.
+- **Errors have `error` (message) and `code` (machine-readable).** Switch on `code`, not `error` — the message may change wording.
 
 ## Links
 

README.md

@@ -91,15 +91,15 @@ const roxy = new Roxy({ client });
 
 ## Error handling
 
-Every method returns `{ data, error, response }`. Check `error` for API errors, or enable `throwOnError` to throw instead.
+Every method returns `{ data, error, response }`. Errors have `{ error: string, code: string }` — switch on `code` for programmatic handling.
 
 ```typescript
 const { data, error } = await roxy.astrology.getZodiacSign({
   path: { identifier: 'aries' },
 });
 
 if (error) {
-  console.error(error);
+  console.error(error.code, error.error); // e.g. "not_found", "Zodiac sign 'xyz' not found"
 } else {
   console.log(data);
 }

docs/llms-full.txt

@@ -644,15 +644,21 @@ const { data } = await roxy.usage.getUsageStats();
 
 ## Error Handling
 
-Every method returns `{ data, error, response }`:
+Every method returns `{ data, error, response }`. All errors have `{ error: string, code: string }`:
+- `error` — human-readable message (may change wording, do not parse)
+- `code` — machine-readable identifier (stable, safe to switch on)
 
 ```typescript
 const { data, error, response } = await roxy.astrology.getDailyHoroscope({
   path: { sign: 'aries' },
 });
 
 if (error) {
-  console.error('API error:', error);
+  // Switch on error.code for programmatic handling
+  if (error.code === 'rate_limit_exceeded') {
+    // wait and retry
+  }
+  console.error('Code:', error.code, 'Message:', error.error);
   console.error('Status:', response?.status);
   return;
 }
@@ -661,11 +667,18 @@ if (error) {
 console.log(data.sign, data.overview);
 ```
 
-Common errors:
-- `401` — Invalid or missing API key
-- `403` — Subscription expired or limit reached
-- `404` — Resource not found (invalid sign, id, etc.)
-- `429` — Rate limited
+Error codes:
+
+| Status | Code | When |
+|--------|------|------|
+| 400 | `validation_error` | Missing or invalid parameters |
+| 401 | `api_key_required` | No API key provided |
+| 401 | `invalid_api_key` | Key format invalid or tampered |
+| 401 | `subscription_not_found` | Key references non-existent subscription |
+| 401 | `subscription_inactive` | Subscription cancelled, expired, or suspended |
+| 404 | `not_found` | Resource not found |
+| 429 | `rate_limit_exceeded` | Monthly quota reached |
+| 500 | `internal_error` | Server error |
 
 ## Advanced Client Configuration