> ## 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. `nextAction` rides on an `octolens onboard` refusal (`EMAIL_ALREADY_REGISTERED`, `SANDBOX_WORKSPACE`, `RESPONSE_LOST`, …): `{kind, command, argv?, retryAfterSeconds?, url?}`, the one move that recovers, in the same vocabulary as the onboard envelope's own `nextAction`.

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 `ENGAGEMENT_METRICS_DISABLED`, `FEED_FILTER_WRITE_CONFLICT`, `FILTER_CONDITION_LIMIT_EXCEEDED`, `FILTER_LIMIT_EXCEEDED`, `KEYWORD_LIMIT_EXCEEDED`, `KEYWORD_OPERATOR_SYNTAX`, `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 |
| - | - |
| `AUTH_LOOKUP_UNAVAILABLE` | — |
| `CONFIG_INVALID` | — |
| `INTERNAL_ERROR` | — |
| `INVALID_RESPONSE` | — |
| `NOT_IMPLEMENTED` | — |
| `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` | — |
| `EMAIL_ALREADY_REGISTERED` | — |
| `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_ENGAGEMENT_FILTER` | — |
| `INVALID_FILTER_JSON` | — |
| `INVALID_FLAG_COMBINATION` | — |
| `INVALID_FORMAT` | — |
| `INVALID_FREQUENCY` | — |
| `INVALID_INTERVAL` | — |
| `INVALID_LIMIT` | — |
| `INVALID_PROFILE_CHOICE` | — |
| `INVALID_RELEVANCE` | — |
| `INVALID_REVIEW_RATING` | — |
| `INVALID_SENTIMENT` | — |
| `INVALID_STORED_BASE_URL` | — |
| `INVALID_TIMEOUT` | — |
| `INVALID_VALUES_JSON` | — |
| `INVALID_WINDOW` | — |
| `JSON_NOT_SUPPORTED` | — |
| `KEYWORDS_STEP_INVALID` | — |
| `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` | — |
| `NOISE_REMOVED_AUTOMATICALLY` | — |
| `NOTHING_TO_UPDATE` | — |
| `NOTIFICATION_TEST_NO_DESTINATIONS` | — |
| `NO_PROFILE_SELECTED` | — |
| `NO_STORED_PROFILE` | non-auth |
| `NO_UPDATE_FIELDS` | — |
| `NO_WEB_PAGE` | — |
| `ONBOARDING_REVISION_CHANGED` | — |
| `ONBOARDING_STEP_NOT_CURRENT` | — |
| `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` | — |
| `WORK_EMAIL_REQUIRED` | — |

### 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` | — |
| `SETUP_DRAFT_NOT_FOUND` | — |

### Exit 5 — permission/scope

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

### Exit 6 — plan/limit

| Code | Auth family |
| - | - |
| `PAYWALL` | — |
| `PLAN_LIMIT_EXCEEDED` | — |
| `QUOTA_EXHAUSTED` | — |
| `SANDBOX_WORKSPACE` | — |
| `SECOND_FREE_TRIAL_FORBIDDEN` | — |

### 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` | — |
| `KEYWORDS_PROPOSAL_FAILED` | — |
| `MCP_CONFIG_WRITE_FAILED` | — |
| `NOTIFICATION_TEST_FAILED` | — |
| `NOTIFICATION_TEST_PARTIAL_FAILURE` | — |
| `SLACK_ROUTE_DELIVERY_FAILED` | — |
| `SLACK_ROUTE_DELIVERY_PARTIALLY_FAILED` | — |

### 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 |
| - | - |
| `ENGAGEMENT_METRICS_DISABLED` | — |
| `FEED_FILTER_WRITE_CONFLICT` | — |
| `FILTER_CONDITION_LIMIT_EXCEEDED` | — |
| `FILTER_LIMIT_EXCEEDED` | — |
| `KEYWORD_LIMIT_EXCEEDED` | — |
| `KEYWORD_OPERATOR_SYNTAX` | — |
| `NO_ORG_MEMBER` | — |
| `ORG_NOT_FOUND` | — |
| `SEARCH_FAILED` | — |
| `WRITE_FAILED` | — |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.