# Errors

Failure envelopes from the tool registry and the MCP server. Read `error_code` and `help_topic`, then `bi_help` that slug. If an error persists after its help topic, call `report_problem`.

## Envelope

A failure has `ok: false` plus the keys that apply: `error`, `error_code`, `category`, `model_next_step`, `operator_next_step`, `retryable`, `error_details`, `help_topic`. Every result that reached a project echoes `project`; project-resolution errors do not. The MCP server echo has `id`, `display_name`, and `partnership_id`. Keys are omitted when they were not set — do not expect every field on every error.

## Categories

- `user_input` — change an input, then retry.
- `needs_config` — an admin must configure something. Escalate. Do not retry.
- `transient` — wait and retry.
- `state` — the object is in the wrong state. Wait, or start a new draft.

## needs_config

Missing credentials, a disabled feature, or a line that is not connected. The operator (or Workspace Admin → Conexiones) fixes it. `help_topic` is `errors#needs_config` when the category is `needs_config` and no more specific slug applies.

## feature_disabled

`FEATURE_DISABLED`: «La funcionalidad 'marketing_console' no esta habilitada para esta alianza.» Pick another project or ask an admin to enable the console.

## roles

`ROLE_DENIED` and `SCOPE_DENIED`: this profile cannot run the tool. Do not retry with the same user. Legacy rank names (viewer, editor, partner_admin) still appear in older tokens; the gate is the capability, not the label.

## confirmation

- `CONFIRMATION_INVALID`: «Token de confirmacion invalido o desconocido.» or «Token de confirmacion invalido para esta conversacion.»
- `CONFIRMATION_ALREADY_USED`: «Este token de confirmacion ya fue usado.»
- `CONFIRMATION_EXPIRED`: «El token de confirmacion expiro.» or «El token de confirmacion expiro. Vuelve a iniciar la accion para obtener uno nuevo.»

Start the action again for a new token. Do not reuse one.

## report_problem

Call it when the operator asks, or after an error whose `help_topic` you already followed and the problem remains. Pass `summary`, `what_i_tried`, and `expected` in the operator's language. Do not paste credentials or phone numbers. Give the operator the `reference` from the result. If `report_problem` itself fails, do not file another report: tell the operator to write to support@frepi.ai.

## Catalog

One line per code emitted by the marketing tools, the confirmation helper, and the MCP server. Next step is the short action.

- `ACCESS_DENIED` — project not reachable. Pass a project from `bi_list_projects`. See `projects#errors`.
- `AUDIENCE_FUENTE_MISMATCH` — audience bound to another fuente. Pick the matching line.
- `AUDIENCE_NOT_FOUND` — no audience with that id in this project.
- `AUDIENCE_OR_PHONE_NOT_FOUND` — audience or line id is missing here.
- `AUDIENCE_REQUIRED` — the call needs an audience.
- `BACKEND_UNREACHABLE` — platform API did not answer. Retry later.
- `BROADCAST_FROZEN_VARIABLE` — greeting collapsed. New list and new draft. See `campaigns#greeting-freeze`.
- `BROADCAST_NOT_CANCELLABLE` — this status cannot be cancelled.
- `BROADCAST_NOT_LAUNCHABLE` — draft cannot send. See `campaigns#launch`.
- `CONFIRMATION_ALREADY_USED` — token already consumed. Start over.
- `CONFIRMATION_ARG_MISMATCH` — confirm args do not match the stashed call.
- `CONFIRMATION_EXPIRED` — token expired. Start over.
- `CONFIRMATION_INVALID` — token unknown or wrong conversation.
- `CONFIRMATION_REQUIRES_CONVERSATION` — confirm needs a conversation id.
- `CONTACTS_CAP` — audience exceeds the contact cap. Narrow it.
- `DUPLICATE_CODE` — template code already exists. Choose another.
- `DUPLICATE_IDEMPOTENCY_KEY` — this idempotency key was already used.
- `DUPLICATE_NAME` — name already taken.
- `EXECUTE_FAILED` — the confirmed action failed. Read `error`.
- `FEATURE_DISABLED` — feature off for this project. See `feature_disabled`.
- `FILTER_COMPILE` — audience filter did not compile. Fix the spec.
- `FUENTE_REQUIRED` — the call needs a fuente.
- `IDEMPOTENCY_KEY_COLLISION` — key collided. Use a new key.
- `INNGEST_SEND_FAILED` — durable send did not enqueue. Retry once.
- `INTERNAL` — unexpected failure. Read `error_details` if present.
- `INVALID_CODE` — template code shape is wrong.
- `INVALID_FILL` — fleet fill recipe is invalid.
- `INVALID_FUENTE` — fuente id is not in this project. Use `list_phone_numbers`. See `lines`.
- `INVALID_ID` — id is not a UUID.
- `INVALID_SPEC` — audience spec shape is wrong. See `campaigns#audience`.
- `INVALID_STATUS` — status filter is not in the allowlist.
- `INVALID_TEMPLATE_COMPONENT` — component shape is wrong.
- `LAUNCH_KEY_UNRESOLVED` — launch could not resolve its idempotency key.
- `NEEDS_PREVIEW` — fleet preview is not ready. See `campaigns#fleet-preview`.
- `NOT_FOUND` — no row with that id in this project.
- `PARTNERSHIP_UNRESOLVED` — partnership for the project could not be read.
- `PHONE_NUMBER_REQUIRED` — the call needs `phone_number_id` (Frepi UUID).
- `PROJECT_ID_REQUIRED` — pass `project_id`. See `projects`.
- `PROJECT_REQUIRED` — no project in context.
- `REPORTER_UNKNOWN` — no operator on this call. A person writes to support@frepi.ai.
- `REPORT_NOT_DELIVERED` — the report was not stored and not emailed. Write to support@frepi.ai.
- `REPORT_RATE_LIMITED` — a report is already on file. Wait, or write to support@frepi.ai if urgent.
- `REPORT_SUMMARY_EMPTY` — write the problem in the operator's words.
- `REPORT_TEXT_TOO_LONG` — shorten the named field and call again.
- `ROLE_DENIED` — role cannot do this. See `roles`.
- `SCHEDULED_AT_INVALID` — bad `scheduled_at`. ISO-8601 with offset, 1 minute to 1 year.
- `SUMMARIZE_FAILED` — summary step failed. Retry later.
- `TEMPLATE_NOT_APPROVED` — template is not approved yet.
- `TEMPLATE_NOT_FOUND` — no template with that id.
- `TENANT_UNCONFIGURED` — workspace data source is not set up. An admin fixes it.
- `UNRESOLVABLE_VARIABLE_KEY` — `config.key` is not in the variable catalog.
- `VALIDATION_ERROR` — input failed validation. Read `error`.
- `WRONG_STATE` — object is in the wrong status for this call.
- `asset_download_failed` — stored asset could not be fetched.
- `asset_error` — asset library returned an error.
- `asset_not_found` — no asset with that id.
- `asset_not_image` — asset is not an image.
- `fuente_missing_meta_access_token` — line has no upload token. See `lines#credentials`.
- `fuente_missing_meta_app_id` — App ID missing (`no_link`, `link_not_live`, `link_pending`).
- `fuente_missing_meta_credentials` — line is missing send credentials.
- `fuente_not_found` — no fuente with that id.
- `fuente_placeholder_credentials` — test credentials still on the line.
- `media_url_not_allowed` — URL is not the upload the tool returned. See `templates#media-headers`.
- `meta_auth` — provider rejected the token. Reconnect the line.
- `meta_invalid_template` — provider rejected the template payload.
- `meta_transient` — provider 5xx or rate limit. Wait and retry.
- `meta_upload_invalid_file` — upload file failed the provider check.
- `s3_not_configured` — media storage is not configured. An admin sets it.
- `template_body_empty` — body text is empty.
- `template_concurrent_change` — template changed under this call. Reload.
- `template_fuente_not_found` — template's fuente is gone.
- `template_header_invalid` — header block is not valid.
- `template_media_failed` — media step failed. Re-upload.
- `template_media_missing` — header file is not stored.
- `template_media_upload_failed` — provider upload failed.
- `template_missing_fuente` — draft has no fuente.
- `template_not_draft` — only a draft can be submitted.
- `template_not_found` — no template with that id.
- `template_not_submittable` — draft is missing a required field.
- `unsupported_media_type` — MIME type is not allowed.
- `upload_failed` — the upload did not finish.