Errores y convenciones

Esta página reúne las reglas que siguen todos los endpoints de la API de Tylode: cómo son los errores, qué significa cada código de estado, cuánto pueden ocupar las listas y cómo tratar las fechas. Conocerlas te ahorra la mayoría de las sorpresas al montar una integración.

#Formato de los errores

Cuando algo falla, la API devuelve un código de estado que no es 2xx y un JSON con el mensaje y un código fijo:

{ "error": "Página no encontrada.", "code": "page_not_found" }

error está pensado para quien lee los registros y puede cambiar en cualquier momento. Sale en el idioma que pida Accept-Language de los trece de la aplicación (por ejemplo Accept-Language: de), en español si no envías la cabecera y en inglés si pides un idioma que no tenemos. code no cambia: si tu programa tiene que distinguir un error de otro, usa el código de estado y code, nunca el texto. Los límites del plan y otros mensajes de la base de datos llevan code: "error" y solo existen en español.

const res = await fetch(url, { headers });
if (!res.ok) {
  const { error } = await res.json().catch(() => ({ error: res.statusText }));
  if (res.status === 429) {
    // espera al minuto siguiente y reintenta
  }
  throw new Error(`Tylode API ${res.status}: ${error}`);
}

La única excepción es el endpoint de tokens de OAuth, que usa el formato estándar de OAuth (error más error_description). Mira Apps OAuth 2.0.

#Códigos de estado

Un 401, 403 o 429 significa que no se ha hecho nada, así que corregir la causa y repetir la petición siempre es seguro.

#Lo que no ves parece vacío

La API actúa como tú y solo devuelve lo que ves en la app. En las listas, eso significa que lo que no te pertenece no da error: simplemente no aparece. Si pasas el ID de un espacio del que no eres miembro, GET /pages?workspace_id=… devuelve { "data": [] } en vez de 403 o 404.

Si una lista llega vacía y esperabas resultados:

1. Llama a GET /workspaces y comprueba que el workspace_id es uno de los tuyos.
2. Comprueba que ves ese elemento en la app. Los tableros, pizarras y bases de datos privados que no se han compartido contigo no aparecen.
3. En apps OAuth, recuerda que lo que cuenta es el acceso del usuario que autorizó la app.

Con elementos sueltos (como GET /pages/:id), lo que no puedes ver devuelve 404, igual que lo que no existe.

#Sin paginación

Los endpoints de listas lo devuelven todo en una sola respuesta; no hay cursores ni páginas. Unos pocos tienen un tamaño fijo:

Todo lo demás (páginas, tableros, tarjetas, eventos, filas, elementos de pizarra…) llega completo. En espacios grandes, pide menos: filtra los eventos del calendario con from y to, o usa la búsqueda en vez de listarlo todo.

#Sin claves de idempotencia

La API no admite claves de idempotencia. Si mandas el mismo POST dos veces, se crean dos páginas, dos tarjetas o dos mensajes.

• Reintenta los GET sin problema.
• Reintenta cualquier petición que haya recibido 401, 403 o 429: no se hizo nada.
• Reintenta un DELETE sin miedo: si ya se hizo, recibes 404 y no pasa nada más.
• No reintentes un POST a ciegas después de un tiempo de espera agotado o un error de red. Puede que sí funcionara. Lista antes (por ejemplo, busca una tarjeta con ese título) y crea solo si falta.
• En los webhooks, que van en sentido contrario, usa el ID de entrega para detectar duplicados. Mira Webhooks.

#Borrar: papelera o para siempre

Los endpoints DELETE hacen lo mismo que borrar en la app:

• Lo que tiene papelera va a la papelera y se puede recuperar desde la app: páginas (con sus subpáginas), tableros, pizarras, presentaciones y archivos de Mi unidad.
• Lo demás se borra para siempre: tarjetas, eventos, filas de bases de datos, diapositivas y elementos de pizarras y diapositivas.

La respuesta dice cuál de las dos ha pasado:

{ "data": { "id": "c4f7a0d3-6b9e-4c2f-8a5d-1e4b7c0f3a96", "papelera": false } }

id es el ID de lo que has borrado, y papelera es true si ha ido a la papelera o false si se ha borrado del todo.

• Si no existe, no puedes verlo, no tienes permiso para borrarlo o ya estaba en la papelera, recibes 404 con code: "not_found_or_cannot_delete".
• Si puedes ver un tablero o una pizarra pero tu rol no te deja mandarlo a la papelera, recibes 403 con el mismo code.
• Las apps OAuth necesitan el permiso :delete del recurso, que va aparte del :write. Mira Permisos.
• Los chats, el correo, las notificaciones y la búsqueda no tienen nada que borrar por la API.

#Fechas y zonas horarias

• Todas las fechas que devuelve la API van en ISO 8601 y en UTC, como 2026-09-23T08:30:00+00:00. Pásalas a hora local en tu código.
• Cuando envíes una fecha (por ejemplo start_at de un evento, o from y to), incluye el desfase o una Z: 2026-10-01T09:00:00+02:00 o 2026-10-01T07:00:00Z. Una hora sin desfase se interpreta en UTC.
• En la query string, codifica el + del desfase como %2B, o usa Z y te olvidas del problema.

#CORS: llama a la API desde un servidor

La API no envía cabeceras CORS, así que el navegador no deja que una página de otro dominio lea sus respuestas. Es a propósito: llamar a la API desde el navegador supondría meter un token que lo puede todo en un código que cualquiera puede leer.

• Llama a la API desde tu servidor, una función serverless o un script.
• Para enseñar algo dentro de Tylode, crea un plugin: habla con la API a través de Tylode, sin token.
• En apps que usan otras personas, usa OAuth y guarda los tokens en tu servidor.

#Versiones

Todos los endpoints cuelgan de /api/v1. Pueden aparecer campos nuevos en las respuestas y endpoints nuevos, así que escribe clientes que ignoren los campos que no conozcan y que no dependan del orden de las claves de un objeto JSON. Los nombres de las cabeceras de los webhooks son estables.

#Páginas relacionadas

• Autenticación: tokens y límites de uso.
• Plataforma para desarrolladores: convenciones e índice de endpoints.
• Solución de problemas: problemas que no son propios de la API.