@zyphr-dev/node-sdk 0.1.37 → 0.1.39

package/README.md

@@ -535,6 +535,45 @@ All error classes extend `ZyphrError`, which extends `Error`:
 | `limitBytes` | `number \| undefined` | Server-enforced body cap (`ZyphrPayloadTooLargeError` only) |
 | `receivedBytes` | `number \| undefined` | Size of the rejected body (`ZyphrPayloadTooLargeError` only) |
 
+### Branch on `error.code`, not `error.message`
+
+`error.code` carries the API's stable, machine-readable code — branch on it
+instead of matching `message` text (which is display copy and may change).
+The code is the exact value from the API response body (e.g. `account_frozen`,
+`account_throttled`, `otp_invalid`, `email_not_found`), not a generic
+per-status placeholder:
+
+> **Behavior change (≥ 0.1.30):** `error.code` now reflects the API's actual
+> machine-readable code for every status. Previously the SDK overwrote it with a
+> generic per-status placeholder (`authentication_error`, `rate_limit_exceeded`,
+> `validation_error`, …). If you were matching those generic strings, switch to
+> `instanceof` for the error *class* and use `error.code` for the specific
+> condition. `error.status` and the error classes are unchanged.
+
+```ts
+try {
+  await zyphr.emails.sendEmail({ /* ... */ });
+} catch (error) {
+  if (error instanceof ZyphrError) {
+    switch (error.code) {
+      case 'account_frozen':      // 403 — sending paused for reputation; see the dashboard
+      case 'account_throttled':   // 429 — sending throttled; back off and retry
+        // ...handle the account's sending state
+        break;
+      case 'otp_invalid':         // 400 — wrong/expired OTP
+      case 'email_not_found':     // 404 — no account for this email (registration fallback)
+        // ...
+        break;
+    }
+  }
+}
+```
+
+The full catalog of codes per endpoint is at
+[zyphr.dev/docs/resources/error-codes](https://zyphr.dev/docs/resources/error-codes).
+Reading `error.code` also flows through the Zyphr MCP server, so agents get the
+same actionable code.
+
 ## Bundle
 
 Dual-format build — works with both ESM and CommonJS: