# Errors Every error class the SDK throws, rooted at `SecondLayerError`. Catch the root to handle all of them, or a subclass to handle one. | Class | Extends | Status | Meaning | | --- | --- | --- | --- | | `ApiError` | `SecondLayerError` | | Error thrown by `SecondLayer` when an API request fails. | | `ArchiveAuthError` | `SecondLayerError` | | Thrown on a 401 from the archive ops host (quote/fetch/credits). | | `ArchiveGateNotConfiguredError` | `SecondLayerError` | | Thrown on a 503 when the archive fetch gate is unconfigured. | | `ArchiveSignatureError` | `SecondLayerError` | | Thrown when an archive manifest signature is missing or does not verify. | | `AuthError` | `ApiError` | 401 | Thrown on a 401 by both the instance clients and Streams. | | `InsufficientArchiveCreditsError` | `SecondLayerError` | | Thrown on a 402 from archive fetch — prepaid credits do not cover the quote. | | `RateLimitError` | `ApiError` | 429 | Thrown on a 429 by both the instance clients and Streams. | | `StreamsServerError` | `ApiError` | | Thrown on a 5xx from the Streams API, and on a failed signing-key fetch. | | `StreamsSignatureError` | `SecondLayerError` | | Thrown when response signature verification is enabled and fails. | | `ValidationError` | `ApiError` | | Thrown on a 4xx the caller can fix (bad cursor, bad params). | ## Notes for agents - Every SDK error extends SecondLayerError; match on the class, not the message. - Status codes shown are the HTTP status the class stands for. ## Setup Ensure setup once, skipping any step already done: - Skill: `bunx skills add ryanwaits/secondlayer --skill secondlayer -y` - CLI: `bun add -g @secondlayer/cli` - Instance: `secondlayer init` writes `INSTANCE_TOKEN`. Loopback `/v1` reads need no key. - Hosted/archive: export `SECONDLAYER_API_KEY` (`sk-sl_*`) or buy credits with `secondlayer credits buy` (`balance`, `refill`), then `secondlayer whoami`