feat: add exit code 3 for rate limiting (DIS-146)

When the OpenSea API returns HTTP 429, the CLI now exits with code 3
and labels the error as 'Rate Limited' instead of the generic 'API Error'.
This allows agents to programmatically detect rate limits and implement
wait-and-retry behavior.

Exit codes: 0=success, 1=API error, 2=auth error, 3=rate limited.

Co-Authored-By: Chris K <ckorhonen@gmail.com>

Author: devin-ai-integration[bot]

.agents/rules.md

@@ -160,9 +160,9 @@ Key aspects:
 ### Error Handling
 
 - API errors are wrapped in `OpenSeaAPIError` (includes status code, response body, path).
-- CLI catches `OpenSeaAPIError` and outputs structured JSON to stderr, then exits with code 1.
+- CLI catches `OpenSeaAPIError` and outputs structured JSON to stderr, then exits with code 1 (or code 3 for rate limiting).
 - Authentication errors (missing API key) exit with code 2.
-- Exit codes: 0 = success, 1 = API error, 2 = auth error.
+- Exit codes: 0 = success, 1 = API error, 2 = auth error, 3 = rate limited (HTTP 429).
 
 ## Design Rules
 

README.md

@@ -169,6 +169,7 @@ console.log(formatToon(data))
 - `0` - Success
 - `1` - API error
 - `2` - Authentication error
+- `3` - Rate limited (HTTP 429)
 
 ## Requirements
 

src/cli.ts

@@ -87,10 +87,11 @@ async function main() {
     await program.parseAsync(process.argv)
   } catch (error) {
     if (error instanceof OpenSeaAPIError) {
+      const isRateLimited = error.statusCode === 429
       console.error(
         JSON.stringify(
           {
-            error: "API Error",
+            error: isRateLimited ? "Rate Limited" : "API Error",
             status: error.statusCode,
             path: error.path,
             message: error.responseBody,
@@ -99,7 +100,7 @@ async function main() {
           2,
         ),
       )
-      process.exit(1)
+      process.exit(isRateLimited ? 3 : 1)
     }
     const label =
       error instanceof TypeError ? "Network Error" : (error as Error).name

test/cli-api-error.test.ts

@@ -0,0 +1,41 @@
+import { Command } from "commander"
+import { afterAll, expect, it, vi } from "vitest"
+import { OpenSeaAPIError } from "../src/client.js"
+
+vi.mock("../src/commands/index.js", () => ({
+  accountsCommand: () => new Command("accounts"),
+  collectionsCommand: () => new Command("collections"),
+  eventsCommand: () => new Command("events"),
+  listingsCommand: () => new Command("listings"),
+  nftsCommand: () => new Command("nfts"),
+  offersCommand: () => new Command("offers"),
+  searchCommand: () => new Command("search"),
+  swapsCommand: () => new Command("swaps"),
+  tokensCommand: () => new Command("tokens"),
+}))
+
+const exitSpy = vi
+  .spyOn(process, "exit")
+  .mockImplementation(() => undefined as never)
+const stderrSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+
+vi.spyOn(Command.prototype, "parseAsync").mockRejectedValue(
+  new OpenSeaAPIError(404, "Not Found", "/api/v2/missing"),
+)
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+it("exits with code 1 and 'API Error' label on non-429 API error", async () => {
+  await import("../src/cli.js")
+  await vi.waitFor(() => {
+    expect(exitSpy).toHaveBeenCalled()
+  })
+
+  expect(exitSpy).toHaveBeenCalledWith(1)
+  const output = stderrSpy.mock.calls[0][0] as string
+  const parsed = JSON.parse(output)
+  expect(parsed.error).toBe("API Error")
+  expect(parsed.status).toBe(404)
+})

test/cli-network-error.test.ts

@@ -0,0 +1,39 @@
+import { Command } from "commander"
+import { afterAll, expect, it, vi } from "vitest"
+
+vi.mock("../src/commands/index.js", () => ({
+  accountsCommand: () => new Command("accounts"),
+  collectionsCommand: () => new Command("collections"),
+  eventsCommand: () => new Command("events"),
+  listingsCommand: () => new Command("listings"),
+  nftsCommand: () => new Command("nfts"),
+  offersCommand: () => new Command("offers"),
+  searchCommand: () => new Command("search"),
+  swapsCommand: () => new Command("swaps"),
+  tokensCommand: () => new Command("tokens"),
+}))
+
+const exitSpy = vi
+  .spyOn(process, "exit")
+  .mockImplementation(() => undefined as never)
+const stderrSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+
+vi.spyOn(Command.prototype, "parseAsync").mockRejectedValue(
+  new TypeError("fetch failed"),
+)
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+it("exits with code 1 on non-API errors", async () => {
+  await import("../src/cli.js")
+  await vi.waitFor(() => {
+    expect(exitSpy).toHaveBeenCalled()
+  })
+
+  expect(exitSpy).toHaveBeenCalledWith(1)
+  const output = stderrSpy.mock.calls[0][0] as string
+  const parsed = JSON.parse(output)
+  expect(parsed.error).toBe("Network Error")
+})

test/cli-rate-limit.test.ts

@@ -0,0 +1,43 @@
+import { Command } from "commander"
+import { afterAll, expect, it, vi } from "vitest"
+import { OpenSeaAPIError } from "../src/client.js"
+
+vi.mock("../src/commands/index.js", () => ({
+  accountsCommand: () => new Command("accounts"),
+  collectionsCommand: () => new Command("collections"),
+  eventsCommand: () => new Command("events"),
+  listingsCommand: () => new Command("listings"),
+  nftsCommand: () => new Command("nfts"),
+  offersCommand: () => new Command("offers"),
+  searchCommand: () => new Command("search"),
+  swapsCommand: () => new Command("swaps"),
+  tokensCommand: () => new Command("tokens"),
+}))
+
+const exitSpy = vi
+  .spyOn(process, "exit")
+  .mockImplementation(() => undefined as never)
+const stderrSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+
+vi.spyOn(Command.prototype, "parseAsync").mockRejectedValue(
+  new OpenSeaAPIError(429, "Rate limit exceeded", "/api/v2/test"),
+)
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+it("exits with code 3 and 'Rate Limited' label on 429 error", async () => {
+  await import("../src/cli.js")
+  await vi.waitFor(() => {
+    expect(exitSpy).toHaveBeenCalled()
+  })
+
+  expect(exitSpy).toHaveBeenCalledWith(3)
+  const output = stderrSpy.mock.calls[0][0] as string
+  const parsed = JSON.parse(output)
+  expect(parsed.error).toBe("Rate Limited")
+  expect(parsed.status).toBe(429)
+  expect(parsed.path).toBe("/api/v2/test")
+  expect(parsed.message).toBe("Rate limit exceeded")
+})