Errores de Plan

Todo error de Plan responde con un estado HTTP y un cuerpo JSON. Decide según el code, pensado para máquinas, nunca según el detail, pensado para personas:

{
  "detail": "This task changed since you loaded it.",
  "code": "version_conflict",
  "extra": { "current_version": 9 }
}

Los errores de validación del cuerpo de una solicitud, en cambio, responden 400 con un mapa de mensajes por campo y sin la clave code. Por ejemplo, un tablero creado sin su proyecto:

{ "project": ["This field is required."] }

Busca primero code; si no está, lee el mapa de campos. Las reglas compartidas por todas las API de Dailybot, incluidos los reintentos, están en Errores.

Durante la Beta, el 402 es lo esperado

Hasta que tu organización tenga habilitada la Beta de Plan, todos los endpoints de Plan responden 402 plan_upgrade_required, sin importar la credencial que uses. Es lo esperado, no un bug: escribe a [email protected] para unirte. GET /v1/plan/entitlements/ es el único endpoint de Plan que nunca responde 402, así que puedes consultar el estado primero.

402 y 503 significan cosas distintas

Respuesta	Significado	Lecturas	Escrituras
402 plan_upgrade_required	Plan no está habilitado para tu organización (un tema del plan o de la Beta)	Rechazadas	Rechazadas
503 feature_temporarily_read_only	Plan está temporalmente en solo lectura durante un incidente	Siguen funcionando	Rechazadas, reintenta más tarde

Manéjalos por separado. Un 503 nunca significa que perdiste el acceso: las lecturas siguen funcionando para que siempre puedas exportar tu trabajo.

El 404 nunca revela qué existe

Una tarea, tablero o proyecto que no existe y uno que pertenece a otra organización devuelven el mismo cuerpo 404. Los filtros se comportan igual: una clave de tablero que no corresponde a nada tuyo simplemente no coincide con nada.

Todos los códigos

400 Bad Request: la solicitud no se pudo aceptar tal como se envió

Código	Estado	Significado	Qué hacer
actor_required	400	La llamada necesita una persona, pero la credencial es una key de agente o de la organización (por ejemplo, owner=me).	Usa una sesión iniciada o una API key personal, o envía el uuid de un usuario en lugar de me.
attachment_invalid_type	400	Ese tipo de archivo no es compatible. Se aceptan imágenes PNG, JPEG, GIF y WebP; PDF; texto plano y Markdown; ZIP; y archivos de Word, Excel y PowerPoint. El servidor revisa el contenido real del archivo, no solo el tipo declarado.	Sube un archivo de un tipo compatible.
attachment_limit_reached	400	La tarea, el comentario, el objetivo o el proyecto ya tiene 50 adjuntos, el máximo.	Quita un adjunto antes de agregar otro.
attachment_too_large	400	El archivo supera el tamaño permitido: 25 MiB con cargas prefirmadas de tareas, 5 MiB en una sola solicitud multipart (la única forma de adjuntar a un comentario, objetivo o proyecto) o en servidores sin almacenamiento de objetos. extra.max_size_bytes indica el límite.	En una tarea, usa presign → carga → confirmación; si no, envía un archivo más pequeño.
channel_not_found	400	Un id de canal que la plataforma conectada no conoce, o un canal privado donde se requiere uno público (extra.parameter: "channel").	Elige un external_id de GET /v1/plan/channels/ (type=channel para un destino personal).
comment_body_too_long	400	El comentario supera los 10.000 caracteres.	Acórtalo o divídelo en varios comentarios.
delta_window_expired	400	El cursor delta tiene más de 7 días.	Vuelve a leer la instantánea del tablero y continúa desde su delta_cursor.
description_too_long	400	La descripción de la tarea supera los 50.000 caracteres.	Acórtala o pasa el detalle a un adjunto.
favorite_limit_reached	400	Ya tienes 50 favoritos.	Quita uno antes de fijar otro.
idempotency_key_required	400	Se envió una llamada masiva sin Idempotency-Key.	Agrega el header; las operaciones masivas siempre lo requieren.
invalid_agent_attribution	400	El nombre del agente supera los 128 caracteres, usa caracteres fuera de letras, números, espacios y . - _ ( ) ' # + / & , :, pertenece a un agente desactivado, o el valor de X-Dailybot-Agent-Name no se puede decodificar como UTF-8 codificado con percent-encoding; o una key de tipo agente envió un nombre de agente. Los nombres nunca se truncan.	Acorta el nombre y codifica el header con percent-encoding, o quita el nombre al llamar con una key de agente. Ver Convenciones de Plan.
invalid_date_range	400	Una fecha o un rango de fechas está mal formado (las fechas son YYYY-MM-DD).	Corrige el formato de la fecha.
invalid_filter_value	400	No se pudo interpretar un filtro, un token de include o un valor de la consulta (por ejemplo, state=overdue). extra.parameter indica cuál.	Corrige el valor; consulta Convenciones de Plan.
invalid_idempotency_key	400	La Idempotency-Key no es una clave válida (de 8 a 128 caracteres).	Envía una clave de 8 a 128 caracteres, por ejemplo un UUID.
invalid_label_filter	400	Un valor del filtro label no es un uuid de etiqueta, o hay más de 50.	Envía hasta 50 uuids de etiqueta.
invalid_relation	400	El vínculo o la referencia no es válido. Por ejemplo: una tarea relacionada consigo misma o con una tarea de otro espacio de trabajo, una tarea asignada como su propia tarea padre, el límite de blocks de la tarea alcanzado, una respuesta a otra respuesta (los hilos tienen un solo nivel), una respuesta a un comentario de otra tarea o una operación masiva desconocida. detail indica cuál.	Lee detail y corrige la referencia.
invalid_schedule	400	Un campo de la programación de un reporte o del resumen no es válido: extra.parameter es weekdays, time, timezone, channel o kind.	Envía días ISO 1–7 (exactamente uno para un reporte semanal), HH:MM, una zona horaria IANA, y un canal o destinatarios de correo.
invalid_sort	400	Esta lista no admite el valor de sort.	Usa una clave de ordenamiento que el endpoint documente.
last_done_state	400	Un tablero debe conservar al menos una columna activa en la categoría done; se rechaza archivar o cambiar de categoría la última.	Agrega primero otra columna done.
milestone_not_on_project	400	El hito pertenece a un proyecto distinto del proyecto del tablero de la tarea.	Elige un hito del proyecto del tablero.
move_board_state_invalid	400	Un movimiento a otro tablero indicó un estado de destino (o un mapa de estados) que no corresponde al tablero de destino.	Envía un state del tablero de destino, o un state_map válido.
notification_routes_limit_reached	400	La organización ya tiene 10 rutas de canal (extra.limit).	Borra o reutiliza una ruta.
participant_cannot_access_board	400	La persona que asignaste como responsable o participante no puede ver el tablero.	Dale acceso al tablero primero, o elige a alguien de …/mentionables/.
platform_not_connected	400	La organización no tiene una plataforma de chat donde publicar o buscar canales.	Conecta primero Slack, Microsoft Teams, Discord o Google Chat.
reaction_invalid_emoji	400	La reacción debe ser un solo emoji (32 caracteres como máximo).	Envía un solo emoji.
reaction_limit_reached	400	Ya tienes el máximo de emojis distintos en este comentario o actualización (extra.limit).	Quita primero una de tus reacciones.
report_schedules_limit_reached	400	La organización ya tiene 10 reportes programados (extra.limit).	Borra o reutiliza un reporte programado.
route_scope_not_org_visible	400	El alcance de una ruta o reporte nombra un tablero o proyecto solo para miembros (extra.uuids). Los canales solo reciben lo que todo el espacio de trabajo puede ver.	Quita esos uuids del alcance.
search_query_too_long	400	El texto de búsqueda supera los 256 caracteres.	Acorta la búsqueda.
search_query_too_short	400	El texto de búsqueda tiene menos de 2 caracteres.	Envía al menos 2 caracteres.
state_not_on_board	400	El estado que indicaste no pertenece al tablero de la tarea.	Usa un uuid de estado de GET …/boards/{board_id}/states/.
states_reorder_invalid	400	La lista de reordenamiento no incluye cada columna activa exactamente una vez.	Envía el uuid de cada estado activo una vez, en orden.
subtask_cross_board	400	Una subtarea debe estar en el mismo tablero que su tarea padre. También se devuelve al mover a otro tablero una tarea que todavía tiene subtareas activas, o que es a su vez subtarea de una tarea del tablero de origen.	Desvincula o mueve primero las subtareas, o deja la tarea en el tablero de su tarea padre.
subtask_depth_exceeded	400	Las subtareas solo se anidan un nivel.	Asígnala a una tarea de primer nivel.
too_many_filter_values	400	Un filtro repetible tiene más de 50 valores (extra.limit da el número exacto).	Envía menos valores por solicitud.
too_many_items	400	La llamada masiva tiene más de 100 elementos.	Divídela en llamadas de hasta 100 elementos.
unknown_field	400	Un campo del cuerpo que el endpoint no acepta (extra.parameter lo nombra). Se rechaza, nunca se descarta en silencio.	Quita el campo.
unknown_notification_kind	400	Un tipo de notificación que no está en el catálogo (extra.parameter: "kind").	Usa una key de GET /v1/plan/notifications/catalog/: tipos personales para tus interruptores, tipos de la organización para una ruta.
update_body_too_long	400	La actualización del proyecto supera los 20.000 caracteres (extra.max_length).	Acorta la actualización.
version_precondition_ambiguous	400	Se enviaron If-Match y el campo version del cuerpo, con valores distintos.	Envía solo uno de los dos.
view_limit_reached	400	Ya tienes 20 vistas guardadas personales en este tablero, el límite.	Elimina una vista antes de guardar otra.

401 Unauthorized: falta la credencial o no es válida

Código	Estado	Significado	Qué hacer
api_key_owner_inactive	401	La persona dueña de la API key fue desactivada.	Crea una clave para una persona activa.
credential_absent	401	No se envió ninguna credencial.	Envía Authorization: Bearer … o X-API-KEY.
credential_expired	401	La credencial venció.	Vuelve a iniciar sesión (dailybot login) o usa una clave vigente.
credential_malformed	401	No se pudo leer la credencial.	Revisa el nombre y el valor del header.
invalid_credentials	401	La clave o el token no existe.	Usa una credencial válida.
plan_free_api_keys_forbidden	401	Las API keys no están disponibles en el plan gratuito.	Usa un token de usuario del CLI, o mejora el plan.
plan_missing_core_api_integrations	401	El plan de la organización no incluye acceso a la API.	Cambia a un plan con acceso a la API.

402 Payment Required: Plan no está habilitado, o se alcanzó un límite del plan

Código	Estado	Significado	Qué hacer
plan_upgrade_required	402	Plan todavía no está habilitado para tu organización. Es lo esperado durante la Beta. (Un inicio de sesión del CLI en el plan gratuito recibe 403 con el mismo código).	Escribe a [email protected] para unirte a la Beta. GET /v1/plan/entitlements/ muestra el estado.
task_boards_limit_reached	402	Se alcanzó el límite del plan para tableros (el plan gratuito incluye hasta 3 tableros).	Archiva un tablero para liberar un lugar, o mejora el plan.
task_projects_limit_reached	402	Se alcanzó el límite del plan para proyectos (el plan gratuito incluye 1 proyecto).	Archiva un proyecto para liberar un lugar, o mejora el plan.

403 Forbidden: iniciaste sesión, pero no tienes permiso

Código	Estado	Significado	Qué hacer
attachment_delete_forbidden	403	Solo quien subió el adjunto o quien administra la organización puede quitarlo; en un comentario, también quien lo escribió.	Pídeselo a quien lo subió, a quien escribió el comentario o a quien administra la organización.
comment_not_author	403	Solo quien escribió este comentario puede editarlo, eliminarlo o adjuntarle archivos.	Pídeselo a quien lo escribió.
guest_not_allowed	403	Las cuentas de invitado no pueden usar Plan.	Usa una cuenta de miembro.
insufficient_scope	403	A la credencial le falta el scope que necesita este endpoint (tasks:read, tasks:write o tasks:admin). La sesión iniciada y la API key personal de un miembro no invitado pueden llamar a todos los endpoints, así que esto significa que los scopes de Plan explícitos de la fila de la key no cubren el endpoint, o que una key de agente o de la organización llamó a un endpoint que requiere una persona.	Usa una API key personal o una sesión iniciada, o agrega el scope que falta a la key. Consulta Autenticación y scopes para Plan.
task_archived	403	Una tarea archivada no se puede duplicar.	Restaura la tarea primero y luego duplícala.
update_not_author	403	Solo la persona autora de una actualización de proyecto puede editarla o adjuntarle archivos; la persona autora o un administrador de la organización puede eliminarla.	Pídeselo a quien la escribió, o a un administrador de la organización para eliminarla.
view_visibility_forbidden	403	Solo quien administra el tablero puede hacer una vista shared o board_default, o editarla o eliminarla.	Deja la vista como personal, o pídeselo a quien administra el tablero.

404 Not Found: el objeto no existe o no es visible para ti

Código	Estado	Significado	Qué hacer
not_found	404	El objeto no existe, o no es visible para ti (por ejemplo un proyecto o tablero members sin grant). Ambos casos devuelven el mismo cuerpo a propósito.	Revisa el identificador. Trátalo como no visible, nunca como “no permitido”.

409 Conflict: la solicitud choca con el estado actual

Código	Estado	Significado	Qué hacer
attachment_not_ready	409	La carga nunca se completó ni se confirmó.	Termina la carga y llama a …/confirm/.
board_not_initialized	409	Al tablero le falta una columna que la operación necesita: no hay columna predeterminada donde crear la tarea, o no hay columna done donde cerrarla.	Agrega la columna que falta al tablero.
duplicate_board_key	409	Otro tablero ya usa esta clave (las claves retiradas siguen reservadas).	Elige otra clave.
goal_name_conflict	409	Ya existe un objetivo activo con este nombre.	Cambia el nombre de uno de los objetivos.
idempotency_in_progress	409	Una llamada con la misma Idempotency-Key todavía está en curso (hasta 120 segundos).	Espera y reintenta con la misma clave.
idempotency_key_payload_mismatch	409	La Idempotency-Key ya se usó con un cuerpo distinto.	Usa una clave nueva para cada operación nueva.
identifier_allocation_failed	409	No se pudo asignar una clave de tarea (KEY-n) porque se estaban creando varias tareas al mismo tiempo.	Reintenta la solicitud con la misma Idempotency-Key.
label_in_use	409	La etiqueta todavía está en uso en tareas, así que no se puede eliminar.	Archívala con PATCH {"is_archived": true}.
last_grant_cannot_be_removed	409	Es el último miembro de un tablero o proyecto restringido a sus miembros.	Agrega otro miembro primero, o hazlo visible para toda la organización.
project_name_conflict	409	Ya existe un proyecto en el espacio de trabajo, activo o archivado, con este nombre.	Elige otro nombre, o cambia el nombre del otro proyecto.
rank_neighbor_missing	409	La tarea after / before cambió de lugar. La respuesta indica la primera y la última tarea actuales de la columna.	Reintenta con una tarea vecina actual.
relation_cycle	409	El vínculo crearía un ciclo.	Vincula las tareas en el sentido contrario, o no las vincules.
relation_exists	409	Las dos tareas ya están vinculadas de esta forma.	No hace falta hacer nada.
state_in_use	409	Todavía hay tareas activas en el estado (columna), o una restauración apunta a un estado archivado.	Envía migrate_to, o restaura a otro estado.
version_conflict	409	La tarea cambió desde que la cargaste. extra.current_version tiene la versión nueva.	Vuelve a leerla, concilia los cambios y reintenta con la versión nueva.

412, 422 y 428: precondiciones y ubicación

Código	Estado	Significado	Qué hacer
column_too_large	422	La columna de destino llegó a su límite de 5.000 tareas.	Mueve o archiva tareas, o divide el tablero.
precondition_failed	412	El validador If-Match de una escritura en una vista guardada está desactualizado.	Vuelve a leer las vistas y reintenta con el nuevo ETag.
precondition_required	428	Se envió una escritura en una vista guardada sin If-Match.	Envía el ETag de tu última lectura.

501 y 503: no disponible por ahora

Código	Estado	Significado	Qué hacer
not_implemented	501	La operación todavía no está disponible. Por ejemplo, definir milestone al crear una tarea: defínelo con PATCH después de crear la tarea.	Usa la alternativa documentada, o revisa el changelog de la API.
attachment_storage_unavailable	503	El almacenamiento de archivos no está disponible temporalmente.	Reintenta más tarde.
feature_temporarily_read_only	503	Plan está temporalmente en solo lectura durante un incidente. Las lecturas siguen funcionando, así que siempre puedes exportar tu trabajo. No es lo mismo que 402.	Reintenta las escrituras más tarde; sigue leyendo con normalidad.

429 Too Many Requests

Si superas un límite de solicitudes (lecturas 120, escrituras 60, masivas 30, feed delta 240 por minuto por actor), la API responde 429 con un header Retry-After. Espera esa cantidad de segundos antes de reintentar. Consulta Convenciones de Plan.

Código	Estado	Significado	Qué hacer
throttled	429	Se alcanzó un límite de solicitudes para este actor. extra.retry_after y el header Retry-After dicen cuántos segundos esperar.	Espera ese tiempo y reintenta.