> For the complete documentation index, see [llms.txt](https://developer.frontitude.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.frontitude.com/developer-cli/errors.md).

# Error handling

> **Note:** The `--error-format` flag is available from CLI version 1.5.0 and above.

Every command exits with a status code your shell or CI pipeline can check:

| Exit code | Meaning                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------- |
| `0`       | Success. The command completed, a dry-run preview was shown, or an interactive prompt was declined. |
| `1`       | Failure. See the error message for details.                                                         |

## Error format

By default, errors are printed as a human-readable message, switching to `json` automatically when `CI=true` is set. That way CI pipelines, scripts, and AI agents get a machine-readable object without extra configuration. You can also request it explicitly with `--error-format json` (or set `FRONTITUDE_ERROR_FORMAT=json`):

```bash
$ frontitude pull --error-format json
{"error":{"code":"UNAUTHENTICATED","message":"Your access token is missing or invalid."}}
```

The object always has the shape `{ "error": { "code": string, "message": string } }`. The `code` is a stable identifier you can branch on; the `message` is a human-readable explanation when one is available.

## Error codes

| Code                   | Meaning                                                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHENTICATED`      | The access token is missing, invalid, or expired. Re-authenticate with `frontitude login` or pass a valid `--access-token`. |
| `FORBIDDEN`            | The authenticated user does not have access to the requested project or resource.                                           |
| `INTEGRATION_DISABLED` | The developer integration add-on is turned off for the workspace. Enable it from the workspace settings.                    |
| `VALIDATION_ERROR`     | The request was rejected because the input was invalid.                                                                     |
| `INVALID_MENTION`      | A `@mention` in a push message did not match an active workspace member.                                                    |
| `UNIQUE_KEY_EXISTS`    | One or more of the keys being pushed already exist in the workspace.                                                        |
| `LIMIT_REACHED`        | The workspace has reached its plan's text-component limit.                                                                  |
| `EXPORT_TOO_LARGE`     | The export is too large to return in a single response. Narrow the pull with filters such as `--pages` or `--tags`.         |
| `NOT_FOUND`            | The requested resource could not be found.                                                                                  |
| `INTERNAL`             | An unexpected server error occurred. Retry, and contact support if it persists.                                             |

New codes may be added over time. The accompanying `message` is a human-readable explanation when one is available.