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):

$ 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.