> ## Documentation Index
> Fetch the complete documentation index at: https://octolens.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# The error envelope

> Every failure renders one envelope: { "error": { "code", "message", "status" } }.

Every failure renders one envelope: `{ "error": { "code", "message", "status" } }`. The three core fields are the contract and are always present; anything else is additive and per-code. `retryAfterSeconds` and `resetAt` ride on `RATE_LIMITED` (exit 7) only when the server stated them — their absence means "not stated", never "retry now". `upgradeUrl` and `upgradeCommand` ride on `UPGRADE_REQUIRED` (the Agents plan wall, exit 6) the same way, naming the upgrade page and the command (`octolens upgrade`) that opens it already signed in.

A real envelope, and a branch on its `code`:

```json theme={null}
{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded", "status": 429, "retryAfterSeconds": 30 } }
```

```sh theme={null}
octolens mentions list --json 2>err.json ||
  case "$(jq -r .error.code err.json)" in
    RATE_LIMITED) sleep "$(jq -r '.error.retryAfterSeconds // 60' err.json)" ;;
    *) jq -r .error.message err.json >&2 ;;
  esac
```

## Every error code

Branch on the envelope's `code` (or the exit code), never on message text. The heading each table sits under is the exit its codes produce.

Every code pins that exit except `KEYWORD_LIMIT_EXCEEDED`, `NO_ORG_MEMBER`, `ORG_NOT_FOUND`, `SEARCH_FAILED` and `WRITE_FAILED`, whose exit is computed at runtime — from the failure itself, or from the HTTP status the API answered with — which is why they sit under their own heading rather than promising an exit they do not choose.

These tables are the enrolled taxonomy, not a ceiling on what a caller can meet. When a resource you asked for by id does not exist, the API answers in its own vocabulary — `FEED_NOT_FOUND` and `MENTION_NOT_FOUND`, and every future `*_NOT_FOUND` like them — forwarded verbatim rather than enrolled here, because that vocabulary belongs to the API and grows with it. For such a code the exit derives from the envelope's HTTP `status` (a 404 exits 4, not found), so branch on the codes you know and fall back to `status` and the exit for one you do not.

One more case is deliberately absent. This build also rejects flags it does not carry, and that rejection is a usage error (exit 2) whose code is not published here — naming it would advertise the flags the rejection hides. So treat an exit-2 code you cannot find on this page as exactly what its exit says: a usage error, not a broken contract.

### Exit 1 — unexpected

| Code                    | Auth family |
| ----------------------- | ----------- |
| `CONFIG_INVALID`        | —           |
| `INTERNAL_ERROR`        | —           |
| `INVALID_RESPONSE`      | —           |
| `REQUEST_TIMEOUT`       | —           |
| `SLACK_CONNECT_TIMEOUT` | —           |
| `UNEXPECTED_ERROR`      | —           |

### Exit 2 — usage

| Code                                | Auth family |
| ----------------------------------- | ----------- |
| `ALREADY_AUTHENTICATED`             | —           |
| `AMBIGUOUS_KEYWORD`                 | —           |
| `AMBIGUOUS_MEMBER`                  | —           |
| `AUTHOR_FILTERS_UNSUPPORTED`        | —           |
| `AUTHOR_NEEDS_SOURCE`               | —           |
| `AUTHOR_REQUIRED`                   | —           |
| `BROWSER_LOGIN_REQUIRES_TTY`        | —           |
| `BROWSER_SIGNUP_REQUIRES_TTY`       | —           |
| `CLEAR_NOT_CONFIRMED`               | —           |
| `COMMAND_NOT_FOUND`                 | —           |
| `CONFLICTING_DESTINATION`           | —           |
| `CONFLICTING_FILTER_FLAGS`          | —           |
| `CONFLICTING_FLAGS`                 | —           |
| `CONFLICTING_TERM`                  | —           |
| `CONFLICTING_VALUE_FLAGS`           | —           |
| `INCOMPLETE_WINDOW`                 | —           |
| `INVALID_ARGUMENT`                  | —           |
| `INVALID_BASE_URL`                  | —           |
| `INVALID_DATE`                      | —           |
| `INVALID_DAY_OF_WEEK`               | —           |
| `INVALID_DELIVERY_MODE`             | —           |
| `INVALID_DESTINATIONS_JSON`         | —           |
| `INVALID_DESTINATION_TYPE`          | —           |
| `INVALID_EMAIL`                     | —           |
| `INVALID_FILTER_JSON`               | —           |
| `INVALID_FLAG_COMBINATION`          | —           |
| `INVALID_FORMAT`                    | —           |
| `INVALID_FREQUENCY`                 | —           |
| `INVALID_INTERVAL`                  | —           |
| `INVALID_LIMIT`                     | —           |
| `INVALID_PROFILE_CHOICE`            | —           |
| `INVALID_RELEVANCE`                 | —           |
| `INVALID_SENTIMENT`                 | —           |
| `INVALID_STORED_BASE_URL`           | —           |
| `INVALID_TIMEOUT`                   | —           |
| `INVALID_VALUES_JSON`               | —           |
| `INVALID_WINDOW`                    | —           |
| `JSON_NOT_SUPPORTED`                | —           |
| `LOGIN_TIMEOUT`                     | —           |
| `MISSING_DESTINATION`               | —           |
| `MISSING_DESTINATION_TARGET`        | —           |
| `MISSING_KEYWORD`                   | —           |
| `MISSING_KEY_VALUE`                 | —           |
| `MISSING_PROFILE`                   | non-auth    |
| `MISSING_REQUIRED_ARGS`             | —           |
| `MISSING_REQUIRED_FLAGS`            | —           |
| `MISSING_SIGNUP_ID`                 | —           |
| `NOTHING_TO_UPDATE`                 | —           |
| `NOTIFICATION_TEST_NO_DESTINATIONS` | —           |
| `NO_PROFILE_SELECTED`               | —           |
| `NO_STORED_PROFILE`                 | non-auth    |
| `NO_UPDATE_FIELDS`                  | —           |
| `NO_WEB_PAGE`                       | —           |
| `PROFILE_URL_LINKEDIN_ONLY`         | —           |
| `REJECT_TARGET_CONFLICT`            | —           |
| `REJECT_TARGET_REQUIRED`            | —           |
| `SIGNUP_TIMEOUT`                    | —           |
| `UNKNOWN_FEED`                      | —           |
| `UNKNOWN_FILTER_LIST`               | —           |
| `UNKNOWN_KEYWORD`                   | —           |
| `USAGE_ERROR`                       | —           |
| `VALIDATION_ERROR`                  | —           |
| `WATCH_REQUIRED`                    | —           |
| `WINDOW_TOO_LARGE`                  | —           |

### Exit 3 — auth

| Code                      | Auth family |
| ------------------------- | ----------- |
| `CONFLICTING_CREDENTIALS` | non-auth    |
| `INVALID_API_KEY`         | non-auth    |
| `MISSING_API_KEY`         | auth        |
| `NOT_LOGGED_IN`           | auth        |
| `NO_CREDENTIALS`          | auth        |
| `NO_PROFILES`             | auth        |
| `UNAUTHORIZED`            | non-auth    |

### Exit 4 — not found

| Code                | Auth family |
| ------------------- | ----------- |
| `KEYWORD_NOT_FOUND` | —           |
| `MEMBER_NOT_FOUND`  | —           |
| `NOT_FOUND`         | —           |
| `PROFILE_NOT_FOUND` | —           |

### Exit 5 — permission/scope

| Code                   | Auth family |
| ---------------------- | ----------- |
| `ADMIN_SCOPE_REQUIRED` | —           |
| `FORBIDDEN`            | —           |
| `INVITER_REQUIRED`     | —           |

### Exit 6 — plan/limit

| Code                  | Auth family |
| --------------------- | ----------- |
| `PLAN_LIMIT_EXCEEDED` | —           |
| `QUOTA_EXHAUSTED`     | —           |

### Exit 7 — rate-limited

| Code           | Auth family |
| -------------- | ----------- |
| `RATE_LIMITED` | —           |

### Exit 8 — cancelled (a human aborted a prompt with EOF/Ctrl-C)

| Code        | Auth family |
| ----------- | ----------- |
| `CANCELLED` | —           |

### Exit 9 — the command ran and the operation did not succeed at its target

| Code                                | Auth family |
| ----------------------------------- | ----------- |
| `FILTERS_ADD_PARTIALLY_REFUSED`     | —           |
| `FILTERS_ADD_REFUSED`               | —           |
| `NOTIFICATION_TEST_FAILED`          | —           |
| `NOTIFICATION_TEST_PARTIAL_FAILURE` | —           |

### Exit 10 — a write was accepted and its answer lost — verify, do not retry

| Code            | Auth family |
| --------------- | ----------- |
| `RESPONSE_LOST` | —           |

### Exit derived from the failure (not pinned)

| Code                     | Auth family |
| ------------------------ | ----------- |
| `KEYWORD_LIMIT_EXCEEDED` | —           |
| `NO_ORG_MEMBER`          | —           |
| `ORG_NOT_FOUND`          | —           |
| `SEARCH_FAILED`          | —           |
| `WRITE_FAILED`           | —           |