Ir al contenido

Leer y escribir contenido

Dentro del servidor no hay HTTP de por medio. Astro.locals.cms habla con D1 directamente, tipado con tus propias colecciones:

---
export const prerender = false
const { docs, pagination } = await Astro.locals.cms.collections.posts.find({
where: { status: { equals: 'published' } },
sort: '-publishedAt',
limit: 10,
})
---
<h1>{pagination.totalDocs} artículos</h1>
{docs.map((post) => <a href={`/blog/${post.slug}`}>{post.title}</a>)}

prerender = false en toda página que lea contenido: en build no hay bindings de Cloudflare y no hay nada que leer. Quien pone ahí locals.cms es la integración de Astro.

Esta lectura funciona sin sesión porque posts declara access: { read: 'public' }. locals.cms es anónimo por defecto: una llamada que no dice quién la hace lanza UnauthorizedError en una colección sin read: 'public' y en toda escritura. Ver Control de acceso.

Es la misma API que usan por dentro la API REST y el administrador. Siete operaciones:

Operación Devuelve Si no existe
find(args?) Una página con sus totales Una página vacía
findByID(id, args?) El documento Lanza NotFoundError
findOne(args?) El primero del orden null
count(args?) Un número 0
create(data) El documento creado —
update(id, data) El documento actualizado Lanza NotFoundError
delete(id) El documento borrado Lanza NotFoundError

findByID lanza y findOne devuelve null a propósito: son dos intenciones distintas, buscar algo que sabes que está o mirar a ver si está.

Todas aceptan, además, { user, overrideAccess }: en el objeto de argumentos de las lecturas y como último argumento de las escrituras. Dicen quién llama, y el control de acceso decide con eso. Sin ellas, la llamada es anónima.

Las siete son de una colección. Un global —la cabecera, el pie, el SEO: un documento único sin listado— cuelga de Astro.locals.cms.globals.<slug> y tiene dos, get() y update(), porque vive en KV y no en D1.

Si la colección declara hooks, corren dentro de la operación, y cada una corre los suyos:

Operación Qué hooks corre
find, findByID, findOne afterRead, una vuelta por documento y después de depth
count Ninguno: no devuelve documentos
create beforeValidate → beforeChange → escritura → afterChange → afterRead sobre la respuesta
update Los mismos cuatro, con originalDoc y previousDoc del documento de antes
delete beforeDelete antes de tocar D1, afterDelete con la fila que desapareció

El orden exacto dentro de cada uno —y dónde entran los hooks de campo— está en Hooks.

where es un objeto de campos y operadores, y se anida con and y or:

await cms.collections.posts.find({
where: {
and: [
{ status: { equals: 'published' } },
{ publishedAt: { less_than: new Date() } },
{ or: [{ title: { contains: 'astro' } }, { author: { in: ['user-1', 'user-2'] } }] },
],
},
})

La lista completa de operadores y de qué tipos admite cada uno está en la referencia.

Un campo de varios valores (hasMany) se filtra con los mismos operadores, contra cualquiera de sus valores: ver más abajo.

Un campo que no existe en la colección lanza QueryError, no se ignora. Un filtro que desaparece en silencio devuelve documentos de más, y eso se descubre tarde y en producción. Lo mismo vale para un operador que no aplica al tipo del campo: contains sobre un checkbox no filtra nada útil, y like sobre un json busca dentro de un blob serializado y parece que funciona hasta que no.

like respeta los comodines de SQL. contains los escapa y envuelve el valor en %…%:

{ excerpt: { contains: '50%' } } // encuentra el texto literal «50%»
{ excerpt: { like: '50%' } } // encuentra todo lo que empieza por «50»

Un buscador de la web va con contains siempre: si no, cualquiera puede escribir % en tu caja de búsqueda y traerse la tabla entera.

Un where escrito en una plantilla trae valores de verdad — un Date, un number, un boolean. El mismo where armado desde una query string trae cadenas. Las dos formas filtran igual:

{ publishedAt: { greater_than: new Date('2026-01-01') } }
{ publishedAt: { greater_than: '2026-01-01' } } // idéntico
{ featured: { equals: 'true' } } // idéntico a `true`

La conversión es solo del where. Lo que se guarda y lo que se lee lo convierte el schema generado, en una única capa: ver Campos.

find() // ORDER BY createdAt DESC, id DESC
find({ sort: 'title' }) // ORDER BY title ASC, id ASC
find({ sort: '-a,b' }) // ORDER BY a DESC, b ASC, id ASC

Al orden que pidas siempre se le añade id como último criterio. No es cosmético: createdAt tiene resolución de milisegundos, y dos documentos creados en el mismo milisegundo se ordenarían de forma arbitraria entre una página y la siguiente, repitiendo unos y saltándose otros. Como el id es un UUID v7, ordenar por él es ordenar por instante de creación, así que el desempate además significa algo.

find devuelve las filas en docs y todo lo demás en pagination:

const { docs, pagination } = await cms.collections.posts.find({ limit: 20, page: 2 })
pagination.totalDocs // 42
pagination.totalPages // 3
pagination.hasNextPage // true

Van juntos en un solo objeto porque casi siempre se pasan juntos: <Paginador {...pagination} /> es todo lo que necesita un componente para pintarse.

limit es un entero entre 1 y 1000, page un entero mayor o igual que 1, y cualquier otra cosa es QueryError — también el limit: 0 que en otros CMS significa «todos». En D1 una lectura sin techo es la forma más fácil de agotar el Worker. Una page más allá del final no es un error: devuelve docs: [] con los totales correctos.

El conteo no cuesta un segundo viaje: las filas y el COUNT(*) van en el mismo batch(), que además es atómico, así que el total corresponde exactamente a la página devuelta.

const { docs } = await cms.collections.posts.find({ select: ['title', 'slug'] })
// ^ docs: { id: string, title: string, slug: string }[]

El tipo de retorno se estrecha con lo que pidas. id entra siempre, lo pidas o no.

Un subcampo de un group se pide por su ruta con puntos, y se filtra y se ordena igual que un campo suelto:

await cms.collections.pages.find({
where: { 'seo.metaTitle': { equals: 'A' } },
sort: '-seo.metaTitle',
select: ['title', 'seo.metaTitle'],
})
// docs: { id, title, seo: { metaTitle } }[]

El tipo de retorno de un select por ruta no se estrecha: seo sigue tipado entero aunque solo venga metaTitle. Pide select: ['seo'] si prefieres que el tipo y el valor coincidan.

Una lista llega siempre en el documento, como un array de filas: [] si no tiene ninguna, nunca null. Cada fila trae su id, y las de un blocks también su blockType. parent y _order, que son de la tabla hija, no salen nunca.

const post = await cms.collections.posts.findByID(id)
post.links // [{ id: '01930d4c-…', label: 'Docs', url: '/docs' }, …]
post.sections // [{ id: '01930d4d-…', blockType: 'hero', title: 'Hola', image: 'm1' }, …]

Las filas salen en el orden en que se escribieron (_order, y el id como desempate, así que dos lecturas seguidas no las intercambian) y con los mismos id. Sus subcampos se leen como los de primer nivel: un date es un Date, un checkbox un booleano, un json el valor y no su texto. El tipo generado (Post['links']) es exactamente lo que esta lectura devuelve con depth: 0.

select decide qué listas se leen. El nombre de la lista la trae entera; un subcampo, no:

find({ select: ['title'] }) // sin listas: ni se consultan
find({ select: ['title', 'links'] }) // links entera, y sections no
find({ select: ['links.label'] }) // QueryError

Lo mismo para where y sort: where: { 'links.label': … } y sort: 'links' son un QueryError (un 400 por REST). Todos dicen la misma frase: una lista no se filtra, ordena ni proyecta por subcampo: se lee entera, con select: ['links'] o sin select. Filtrar y ordenar por las filas llega más adelante.

Un global lee sus listas igual, desde su clave de KV: mismas filas, mismos id (la posición, en las guardadas antes de tenerlo) y mismo select.

Las filas heredan el acceso del documento. Lo que el access.read de la colección deja fuera —un Where o un «nada»— no trae filas, porque no trae documento. Si una lista declara su propio access.read y el actor no lo cumple, la lista no sale, como cualquier campo. El afterRead de la lista y el de la colección ven la lista entera, con las relaciones de sus filas ya resueltas si hay depth.

Cuesta una sentencia por tabla hija, no por fila

Sección titulada «Cuesta una sentencia por tabla hija, no por fila»

Las tablas hijas se leen en el mismo batch() que el documento: con T tablas hijas (un array es una; un blocks, una por cada tipo de bloque), find cuesta T + 2 sentencias —las filas, el COUNT(*) y las tablas hijas—, y findOne y findByID cuestan T + 1, en un solo viaje a D1. No dependen de cuántas filas tenga una lista ni de cuántos documentos haya en la página. Una colección sin listas, o un select que no nombra ninguna, siguen costando lo que costaban.

Lo que sí crece con T es el trabajo de la base: cada sentencia vuelve a evaluar el where y el orden de la página para saber de qué documentos son las filas. Si no vas a pintar una lista, no la pidas en el select.

Un campo con hasMany: true llega siempre en el documento como un array de valores, en el orden en que se escribieron: [] si no tiene ninguno, nunca null. Los valores salen sueltos, sin id ni _order.

const post = await cms.collections.posts.findByID(id)
post.tags // ['tech', 'news']
post.scores // [3, 1, 2] el orden de escritura, no el numérico
post.keywords // [] si nunca se escribió o se vació

select decide qué campos se leen, y el nombre de un hasMany lo trae entero (select: ['title', 'tags']); sin select vienen todos. sort por un hasMany es un QueryError (un 400 por REST): un documento no tiene un único valor por el que ordenarlo. depth hidrata las relaciones y el hasMany de cada documento hidratado llega también. Los hasMany de relationship y upload tienen su propia sección.

Cada condición sobre un hasMany pregunta por cualquiera de sus valores:

Operador Se cumple cuando…
equals, in, like, contains, greater_than… algún valor cumple la condición
not_equals, not_in ningún valor cumple equals / in: es el complemento, y un documento sin valores pasa
exists: true tiene al menos un valor
exists: false no tiene ninguno: [] y «nunca se escribió» son lo mismo
await cms.collections.posts.find({ where: { tags: { in: ['news', 'tech'] } } }) // alguna es news o tech
await cms.collections.posts.find({ where: { tags: { not_equals: 'news' } } }) // ninguna es news
await cms.collections.posts.find({ where: { scores: { greater_than: 5 } } }) // alguna puntuación supera 5

Por REST, igual:

GET /api/cms/posts?where[tags][equals]=news
GET /api/cms/posts?where[tags][in][0]=news&where[tags][in][1]=tech
GET /api/cms/posts?where[tags][exists]=false
  • equals y not_equals del mismo valor reparten la colección en dos: ni un documento en los dos ni uno en ninguno. Eso es lo que hace de not_equals «ninguno es…» y no «alguno no es…», y por eso un post con las etiquetas news y tech no sale con not_equals: 'tech'.
  • Cada condición tiene su propia comprobación. Para pedir dos valores a la vez, dos condiciones: and: [{ tags: { equals: 'news' } }, { tags: { equals: 'tech' } }]. Un operador no puede pedir dos valores.
  • equals con una lista es un QueryError, nunca «igual a alguno»: para eso está in. Por REST, repetir where[tags][equals]=a&where[tags][equals]=b llega como una lista y es un 400.
  • Un número llega como texto por REST y se compara como número, igual que en un campo de siempre.
  • El where de lectura puede nombrarlos, el de escritura no. Un access.read que devuelve { tags: { equals: 'news' } } filtra las lecturas. Uno de access.update o de access.delete con un hasMany se rechaza con un AccessError (un 500 por REST, con el motivo en el registro del Worker), porque esa condición se vuelve a comprobar después de que la escritura reemplace los valores que lee. Ver Limitaciones.
  • No añade sentencias, pero tampoco hay índice sobre el valor: cada condición recorre los valores de los documentos candidatos. Con muchos documentos y un filtro frecuente por un valor, valora un campo normal con index.

Un hasMany de relationship o upload llega en el documento como un array, en el orden en que se escribió y nunca null: ids con depth: 0, documentos con depth: 1. Con una colección en to es una lista de ids; con varias, de pares { relationTo, value }.

const post = await cms.collections.posts.findByID(id, { depth: 0 })
post.categories // ['c1', 'c2']
post.related // [{ relationTo: 'pages', value: 'p1' }, { relationTo: 'categories', value: 'c3' }]
const hydrated = await cms.collections.posts.findByID(id, { depth: 1 })
hydrated.related[0].value // el documento de la página p1, con su colección en relationTo

depth los hidrata por lote y por nivel, como cualquier relación: una consulta por colección destino y nivel, con los ids repartidos de 100 en 100 (D1 admite 100 variables por sentencia), no una por documento ni por elemento. Un find de 50 posts con tres campos de este tipo cuesta las mismas consultas que uno de 5.

  • Cada destino se vuelve a autorizar. Un elemento hacia una colección que quien llama no puede leer se queda como el id (en un polimórfico, como { relationTo, value: 'p1' }); publicOnly hace lo mismo con las cerradas.
  • La carpeta reservada de ssd no se hidrata: un fichero de .system en una galería sale con su id.
  • Un id que ya no resuelve se queda como el id. Nunca rompe la lectura.
  • Los destinos traen sus propias listas. Lo que depth: 1 trae de una colección con un hasMany lo trae como ids (una consulta por tabla hija); con depth: 2 esas listas se resuelven en la ronda siguiente.
  • La lectura ordena por _order y no supone que sea contiguo: tras borrar un destino con onDelete: 'setNull' la lista conserva el orden de los que quedan.

Cada condición pregunta por cualquiera de los elementos, con las mismas reglas de los valores sueltos (not_equals y not_in son el complemento, exists: false es la lista vacía):

await cms.collections.posts.find({ where: { categories: { equals: 'c1' } } }) // alguna es c1
await cms.collections.posts.find({ where: { gallery: { in: ['m1', 'm2'] } } }) // alguna foto es m1 o m2
await cms.collections.posts.find({ where: { categories: { exists: false } } }) // ninguna

Con varias colecciones, un id solo no dice de cuál es: el campo se filtra por la colección.

Clave del where Pregunta
related.pages algún elemento es de pages y su id cumple la condición (equals, in, not_equals, not_in, exists)
related.relationTo de qué colección es algún elemento: equals, in, not_equals, not_in con el nombre de la colección
related solo exists: si tiene algún elemento. Con otro operador es un QueryError que dice cómo filtrar
await cms.collections.posts.find({ where: { 'related.pages': { equals: 'p1' } } })
await cms.collections.posts.find({ where: { 'related.relationTo': { in: ['pages'] } } })

Por REST: GET /api/cms/posts?where[related.pages][equals]=p1.

Reglas que no cambian: sort por un hasMany es un QueryError; el where de un access.update o access.delete que nombre uno se rechaza con un AccessError; filtrar no añade sentencias, y sí hay un índice (una columna por colección destino), así que equals e in sobre el id no recorren la tabla. Una fila con todas las columnas a NULL no es un elemento y exists no la cuenta.

depth Qué devuelve un campo relationship o upload
0 El id: '01930d4c-…'
1 El documento entero, con sus propias relaciones en ids
n Se repite hasta n niveles (máximo 10)

Por defecto es 1, que es lo que casi siempre quieres al pintar una plantilla. Un campo upload se resuelve igual que un relationship.

depth re-autoriza cada destino: una relación solo se resuelve si quien llama puede leer la colección a la que apunta. Si no puede, se queda el id, como si el documento no existiera. Una llamada anónima, que es la de por defecto, hidrata hacia las colecciones con read: 'public' —la biblioteca ssd lo es— y no hacia users: para que author llegue resuelto en una página que decide qué mostrar, la llamada lleva overrideAccess: true.

Por eso el tipo generado es una unión y no solo el id:

interface Post {
cover: string | Medio | null
}

Con depth decidido en tiempo de ejecución, TypeScript no puede saber qué rama toca, así que lo dice. Estrechas al usarlo:

---
const ssd = Astro.locals.cms.collections.ssd
---
{typeof post.cover === 'object' && post.cover !== null && (
<img src={ssd.url(post.cover)} alt={post.cover.alt ?? ''} />
)}

El documento resuelto trae sus campos —filename, mimeType, alt…— pero no una url: la ruta la construye url(), que vive en la colección upload. Ver Ficheros.

Un id que no resuelve se queda como la cadena que era. La fila puede haberse borrado entre dos consultas, o alguien puede haber escrito en D1 por fuera. Ni se pierde el id —que es la única pista para saber de dónde venía— ni se cae un listado de cincuenta artículos por una referencia rota.

Cuesta consultas fijas, no una por documento

Sección titulada «Cuesta consultas fijas, no una por documento»

Por cada nivel se agrupan todos los ids que apuntan a la misma colección, se deduplican y se lanza una sola consulta por colección de destino. Cincuenta artículos con autor y portada son tres consultas, no cincuenta y una.

depth también entra en las filas. Un relationship o un upload dentro de una fila de una lista se resuelve con las mismas reglas que uno de primer nivel —re-autoriza el destino, y lo que el actor no puede leer se queda como id—, y los documentos que trae consigo sus listas: post.author.links existe con depth: 1. Las filas de lo hidratado se leen con una sentencia por tabla hija y nivel, en un solo batch(), sea cual sea el número de documentos. Cincuenta artículos con autor y portada, y una lista de enlaces con un relationship en cada fila, siguen siendo consultas fijas.

Un upload roto dentro de una fila no tumba la lectura, igual que en primer nivel. Si borras el medio, la celda de la fila queda en null (la clave foránea es ON DELETE SET NULL) y se lee null. Si el id no resuelve —un medio de una carpeta reservada, un destino cerrado, una fila escrita por fuera— se queda el id.

Escribir exige sesión, y una llamada sin quién la hace es anónima. En los ejemplos de esta sección escribe el servidor —un seed, un endpoint tuyo que decide—, así que cada llamada lleva overrideAccess: true. Si escribe una persona y debe valer lo que ella puede, en su lugar va { user }, o la API envuelta con forUser.

const post = await cms.collections.posts.create(
{
title: 'Hola',
slug: 'hola',
status: 'published',
cover: 'a1b2c3d4-…', // en escritura, una relación es siempre el id
},
{ overrideAccess: true },
)

create valida contra el esquema de la colección, aplica los defaultValue a lo que falte, genera id, createdAt y updatedAt, inserta y devuelve el documento con sus relaciones ya resueltas y pasado por el afterRead de la colección, si declara alguno: lo devuelto es lo que daría una lectura, no la fila cruda. Lo que se guarda no cambia (ver Hooks).

El id lo genera siempre el CMS, un UUID v7. Pasarlo a mano se rechaza, igual que createdAt y updatedAt. Es lo que hace que todos los ids sean ordenables por tiempo por construcción: los 48 bits altos de un v7 son el timestamp en milisegundos, así que el índice de la clave primaria sirve además de índice de orden de creación.

update es parcial. Lo que no mandes se queda como estaba, y updatedAt se refresca siempre:

await cms.collections.posts.update(post.id, { title: 'Hola de nuevo' }, { overrideAccess: true })

Con un group la parcialidad baja un nivel: update(id, { seo: { metaTitle: 'A' } }) cambia ese subcampo y conserva los hermanos, y { seo: null } los pone todos a null. Un point se escribe de una pieza, [lng, lat], o null.

Si lo que escribes sale de una lectura anterior —un formulario, una integración que lee y reescribe— puedes pedir que la escritura aplique solo si nadie tocó el documento entre medias, pasando el updatedAt que leíste en ifMatch. Si ya no coincide, no se escribe nada y salta PreconditionFailedError; relee y reintenta. Es opcional, y la API REST lo expone como If-Match:

await cms.collections.posts.update(
post.id,
{ title: 'Hola de nuevo' },
{ ifMatch: post.updatedAt.toISOString(), overrideAccess: true },
)

delete devuelve el documento borrado, para que puedas registrar qué desapareció —o deshacerlo— sin una lectura previa. Como las demás escrituras, acepta { user, overrideAccess } como segundo argumento:

await cms.collections.posts.delete(post.id, { overrideAccess: true })

Una lista de filas (array y blocks) se escribe por reemplazo: la lista que mandas es la que queda.

const post = await cms.collections.posts.create(
{
title: 'Hola',
slug: 'hola',
status: 'published',
links: [{ label: 'Inicio', url: '/' }, { label: 'Blog', url: '/blog' }],
sections: [{ blockType: 'hero', title: 'Bienvenida' }],
},
{ overrideAccess: true },
)
// post.links[0].id → 'a1b2…': un UUID v7 por fila, acuñado por el servidor
await cms.collections.posts.update(
post.id,
{ links: [post.links[1], { label: 'Contacto', url: '/contacto' }] },
{ overrideAccess: true },
)
// links: la fila 'Blog' (con su id) y la nueva, en ese orden. 'Inicio' desaparece.
  • update sigue siendo parcial por campo: una lista que no mandas no se toca, links: [] la vacía y links: null es un 400 (INVALID_TYPE). No hay parches por fila: se manda la lista entera.
  • create, update y delete devuelven el documento con sus listas, y los hooks (beforeChange, afterChange, originalDoc, previousDoc) las ven enteras.
  • Las filas con id lo conservan y las demás reciben un UUID v7. El id es único dentro del documento, no entre documentos.
  • El documento y todas sus filas se escriben en un solo batch() de D1, con las mismas sentencias para 10 filas que para 1000; si una falla, no se escribe nada. Un 404 o un 412 no tocan ninguna tabla hija.

Un campo con hasMany se escribe por reemplazo, como una lista de filas: el array que mandas es el que queda.

const post = await cms.collections.posts.create(
{ title: 'Hola', slug: 'hola', status: 'draft', tags: ['news', 'tech'], scores: [3, 1, 2] },
{ overrideAccess: true },
)
await cms.collections.posts.update(post.id, { tags: ['life'] }, { overrideAccess: true })
// tags queda ['life']; scores no se toca
  • Ausente no toca; [] vacía; null es un 400 (INVALID_TYPE sobre el campo). Vaciar un campo es tags: [], y un required lo rechaza (REQUIRED).
  • El orden y los duplicados se conservan: ['b', 'a', 'b'] se guarda y se lee tal cual. Un valor falso (0, '') es un valor como cualquier otro.
  • Cada valor se valida con su ruta: tags.1 es el segundo (INVALID_OPTION si no está en las opciones del select, NOT_INTEGER, MAX_LENGTH…), y la lista entera puede dar REQUIRED, MIN_ROWS o MAX_ROWS.
  • Se guarda en el mismo batch() que el documento, con una sentencia por tabla hija: las mismas sentencias para 3 valores que para 100. Si una falla, no se escribe nada; un 404 o un 412 no tocan los valores; y delete los borra con el documento.
  • No hay «añadir un valor». Para cambiar uno se lee el array y se manda entero. Sin ifMatch, dos guardados a la vez del mismo campo son last-write-wins sobre toda la lista de valores, como en una lista de filas.
  • Los hooks (beforeValidate, beforeChange, afterChange, afterRead, los del campo incluidos) ven y pueden devolver el array; lo que devuelven se vuelve a validar.

Igual que los demás: por reemplazo, con ids (o con { relationTo, value } en un polimórfico).

await cms.collections.posts.update(
post.id,
{ categories: ['c3', 'c1'], related: [{ relationTo: 'pages', value: 'p1' }], gallery: [] },
{ overrideAccess: true },
)
  • Cada elemento se valida con su ruta. Un id que no existe es INVALID_RELATION en categories.1, con el nombre de la colección; un fichero que el accept del campo no admite, INVALID_FILE_TYPE en gallery.1; una colección que el campo no admite, INVALID_OPTION en related.0.relationTo. Salen todos juntos.
  • El camino que funciona no paga la comprobación de existencia: la clave foránea la hace en el mismo batch(), y solo si falla se hace una consulta (por colección destino, de 100 ids en 100) para decir qué elementos faltaban.
  • Todo o nada: el documento y todas sus listas van en un solo batch(). Si un elemento falla, ni el padre ni ninguna lista cambia. Y un destino que se borra entre la validación y la escritura es el mismo INVALID_RELATION, no un 500.
  • Borrar un documento borra las filas de sus listas. Borrar un destino depende de onDelete: 'setNull' quita el elemento de la lista; 'restrict' no deja borrarlo (RESTRICTED, con el nombre del documento y del campo).

Todos heredan de CMSError y llevan un code estable y un status. El mensaje es para humanos y puede cambiar; el code no.

Clase code status Cuándo
ValidationError VALIDATION_ERROR 400 El documento no pasa el esquema, o choca un constraint
QueryError QUERY_ERROR 400 where, sort, select, limit, page o depth mal formados
UnauthorizedError UNAUTHORIZED 401 No hay sesión y access no deja pasar: lo que pasa con una llamada anónima, que es la de por defecto
ForbiddenError FORBIDDEN 403 Hay sesión y la función de access dice que no
NotFoundError NOT_FOUND 404 El documento no existe, o una condición de access lo deja fuera: el mismo error y el mismo texto
PreconditionFailedError PRECONDITION_FAILED 412 El ifMatch de update ya no coincide con el updatedAt
DatabaseError DATABASE_ERROR 500 D1 ha fallado; el error original va en cause

ValidationError trae un issues con un problema por campo, que es lo que el administrador pinta debajo de cada uno:

try {
await cms.collections.posts.create(
{ title: 'Repetido', slug: 'hola', status: 'draft' },
{ overrideAccess: true },
)
} catch (error) {
if (error instanceof ValidationError) {
console.log(error.issues)
// [{ path: 'slug', code: 'UNIQUE', message: 'Ya existe un documento con ese slug' }]
}
}

Un slug duplicado o una relación que apunta a un documento inexistente son errores de quien escribe, no del servidor, así que salen como 400 con el campo culpable señalado y no como un fallo interno:

Lo que falla code del issue
Un unique que ya existe UNIQUE
Una relación a un id que no existe INVALID_RELATION (si está dentro de una fila, sobre la lista: links)
Borrar algo a lo que otros apuntan con onDelete: 'restrict' RESTRICTED

Lo que no encaje con ninguno de esos patrones cae a DatabaseError 500 sin inventar nada: un error mal traducido es peor que uno genérico.