Guías

Errores

En esta página

Formato de las respuestas

Las respuestas con cuerpo van dentro de data:

JSON

{ "data": { "id": "…", "title": "…" } }

Los listados paginados (GET /tasks) añaden nextCursor; GET /projects no pagina y no lo lleva:

JSON

{ "data": [], "nextCursor": "1765804800000:abc…" }

Formato de los errores

Los errores tienen siempre la misma forma:

JSON

{ "error": { "code": "invalid_api_key", "message": "Invalid API key" } }

Programa contra el code y el status HTTP. El message es texto para personas y puede cambiar sin aviso.

Códigos

HTTP	Código	Cuándo
401	`invalid_api_key`	Falta la clave, está mal formada, no existe, está revocada o ha caducado.
403	`insufficient_scope`	La clave no tiene el permiso que pide el endpoint.
403	`forbidden`	El recurso existe pero no tienes acceso a él.
404	`not_found`	El recurso no existe, no tienes acceso o el id está mal formado.
422	`invalid_json`	El cuerpo no es JSON o no es un objeto.
422	`unknown_field`	El cuerpo trae un campo que el endpoint no acepta.
422	`missing_field`	Falta un campo obligatorio.
422	`invalid_field`	Un campo tiene un tipo o un valor no válido.
422	`invalid_query_param`	Un parámetro de la URL tiene un tipo o un valor no válido.
422	`empty_patch`	Un `PATCH` sin ningún campo que cambiar.
422	`body_too_large`	El cuerpo pasa de 64 KB.
422	`invalid_idempotency_key`	La `Idempotency-Key` es demasiado larga o tiene un formato no válido.
422	`validation_error`	Validación general, como un `projectId` mal formado o una recurrencia sin `deadline`.
409	`recurring_scope_required`	`DELETE` de una tarea recurrente sin `?scope=occurrence\|series`. No se borra nada.
409	`project_archived`	La tarea está en un proyecto archivado, que es de solo lectura. No se aplica nada.
403	`calendar_creator_only`	Cambias la sincronización con el calendario de una tarea que creó otra persona.
422	`assignee_not_member`	El `assigneeId` no es de alguien con acceso al proyecto de la tarea.
422	`task_not_shared`	Asignas una tarea que no está en un proyecto compartido.
422	`task_private`	Asignas una tarea privada, creada por una integración.
429	`rate_limited`	Has superado los límites de uso; espera lo que indica `Retry-After`.
500	`internal_error`	Error del servidor. Reintenta con espera creciente.

Cuándo aparece cada uno

Clave y permisos

invalid_api_key (401): falta la clave, está mal formada, no existe, está revocada o ha caducado. No se distingue el motivo.
insufficient_scope (403): la clave no tiene el permiso que pide el endpoint.
forbidden (403): el recurso existe pero no tienes acceso, por ejemplo al mover una tarea a un proyecto de otra persona.
calendar_creator_only (403): intentas cambiar la sincronización con el calendario de una tarea que creó otra persona.

Recursos

not_found (404): el recurso no existe, no tienes acceso o el id está mal formado.

Nota

En /tasks/{id} una tarea a la que no tienes acceso responde igual que una que no existe: la API no revela si existe.

Conflictos

recurring_scope_required (409): DELETE de una tarea recurrente sin ?scope=occurrence o ?scope=series. No se borra nada.
project_archived (409): intentas editar o borrar una tarea de un proyecto archivado, que es de solo lectura. No se aplica nada.

Datos de entrada

Los cuerpos son estrictos: un campo que el endpoint no acepta se rechaza en vez de ignorarse.

invalid_json (422): el cuerpo no es JSON o no es un objeto.
unknown_field (422): el cuerpo trae un campo que el endpoint no acepta (¿una errata?).
missing_field (422): falta un campo obligatorio, como title, name o recurrence.frequency.
invalid_field (422): un campo tiene un tipo o un valor no válido.
invalid_query_param (422): un parámetro de la URL tiene un tipo o un valor no válido.
empty_patch (422): un PATCH sin ningún campo que cambiar.
body_too_large (422): el cuerpo pasa de 64 KB.
invalid_idempotency_key (422): la Idempotency-Key es demasiado larga o tiene un formato no válido.
validation_error (422): validación general, por ejemplo un projectId con formato no válido o una recurrencia sin deadline.

Asignaciones

assignee_not_member (422): el assigneeId no es de alguien con acceso al proyecto de la tarea.
task_not_shared (422): intentas asignar una tarea que no está en un proyecto compartido.
task_private (422): intentas asignar una tarea privada, creada por una integración.

Límites y servidor

rate_limited (429): has superado los límites de uso. Espera los segundos que indica la cabecera Retry-After.
internal_error (500): error del servidor. El mensaje es opaco a propósito; reintenta con espera creciente.