Escritura rechazada: qué hacer

En una línea: cómo distinguir las razones por las que se rechaza una escritura, y cuál es el paso siguiente de cada una.

Lee el código antes de reintentar

Una escritura rechazada tiene varias causas que no tienen nada que ver entre sí, y sus arreglos tampoco. El código de error es la forma de distinguirlas:

Código	Estado	Qué significa	Paso siguiente
AI_READONLY_FILE_TYPE	403	Este tipo no acepta escrituras de archivo completo	Archivo estructurado: usa la herramienta update_* que nombra el mensaje. .character / .json y compañía: no hay alternativa
SUBSCRIPTION_REQUIRED	403	La capacidad pertenece a los planes de suscripción	La lectura no está restringida: lee el archivo y describe el cambio que recomiendas
INVALID_PATH	400	Un libro antiguo de Script Studio, escrito fuera del árbol de planificación	Escribe bajo .script_studio/planning/
FOLDER_NOT_EMPTY	422	La carpeta que pediste borrar tiene cosas dentro	Si va en serio, reenvíalo con recursive: true

En ninguno de esos cuatro casos reenviar los mismos argumentos se convierte en un éxito.

1 · Archivos estructurados: el mensaje nombra la herramienta

Apunta write_file, edit_file o append_to_file a un .map, .beats, .timeline, .script o .geomap y esto es lo que recibes:

.map files are structured documents — a generic write would corrupt them.
Use POST /api/v1/books/:book_token/mcp/files/structured (the MCP client
exposes it as update_relationship_map): it takes one field-level operation at
a time, so the parts of the document you were never shown cannot be dropped.
If update_relationship_map is not in your tool list, your Slima MCP client is
older than this server — ask the author to update the Slima MCP package.
A missing tool always means an out-of-date client; nothing about this account
ever hides a tool from you.

Ahí dentro van dos cosas: qué herramienta usar y qué hacer cuando esa herramienta no está en tu lista. Lo segundo importa, porque 0.2.0 no tiene esas herramientas y el servidor tampoco acepta escrituras de archivo completo: un cliente antiguo tiene las dos vías cerradas. La actualización está en Cómo funcionan las versiones de slima-mcp.

.character, .location, .json y .yaml devuelven el mismo código sin la parte de la vía alternativa: lee el archivo y di con palabras qué cambiarías.

2 · La barrera de la suscripción: leer nunca está restringido

Cuando el plan no ha desbloqueado la escritura estructurada, el código es SUBSCRIPTION_REQUIRED y el mensaje dice:

Writing .map files is part of Slima's subscription plans. Reading them is not
restricted — read the file and describe the change you recommend, and the
author can make it in the app or subscribe to let you make it directly.
(Credits bought as a one-off pack cover AI usage inside the Slima app;
structured file writing goes with a plan.)

De ahí se siguen tres cosas:

• La lectura queda intacta. Una IA en una cuenta Free puede leer todos los .map y .timeline del libro. Lo que no puede es cambiarlos.
• La prueba es el plan, no si alguna vez se gastó dinero. Un paquete de créditos suelto cubre el uso de IA dentro de la app de Slima; no desbloquea la escritura estructurada.
• Borrar está controlado igual que escribir. En un plan Free, un .map no se puede crear, no se puede editar y tampoco se puede borrar.

La respuesta útil aquí no es reintentar. Es leer el archivo y decir con precisión qué cambiarías, para que el autor pueda hacerlo en la app.

3 · Libros antiguos de Script Studio: INVALID_PATH

Si el libro es uno antiguo de Script Studio se aplica un conjunto de reglas completamente aparte, y funciona por rutas: la única zona escribible es el árbol .script_studio/planning/, mientras que series.json, *.character, *.location, *.scene, *.storyline, *.note y .script_studio/planning/.initialized son de solo lectura a través de MCP.

.script_studio/planning/scene-3-1-revision.md   ← se puede escribir
Episodes/03/scene-1.scene                        ← 400 INVALID_PATH

La salida es escribir la propuesta en ese árbol de planificación y dejar que el autor la aplique en la app. Para conocer las reglas antes de intentarlo, lee el recurso slima://books/{book_token}/schema, o simplemente llama a get_book: en uno de esos libros imprime él mismo sus restricciones de escritura.

4 · La más fácil de pasar por alto: funcionó, y el archivo está vacío

A create_file no se le rechaza en las cinco extensiones estructuradas. Funciona, y lo que el servidor escribió es un esqueleto vacío, con el contenido que enviaste descartado. La respuesta lo dice con todas las letras.

Como no es un fallo, se lee como «creado». El flujo correcto son dos pasos: create_file para tener uno vacío y después lotes de update_* para llenarlo.

Dos causas que no van del tipo de archivo

• El libro está en la papelera. Un libro en la papelera no se puede escribir. Restáuralo primero.
• El libro te lo compartieron. Sin acceso de escritura sobre ese libro, solo puedes leer.

No rodees un rechazo

Los errores de MCP en Slima están escritos para poder arreglarse desde el propio mensaje: un id desconocido vuelve con los ids reales, un nivel de lugar desconocido con los niveles reales, un campo mal colocado con el nombre de la operación a la que pertenece. El coste de un atajo lo paga el autor; el coste de leer el mensaje lo pagas tú, y es mucho más barato de los dos.

Relacionado

• Docs: Protección de archivos estructurados
• Docs: Herramientas de edición estructurada
• Docs: Cómo funcionan las versiones de slima-mcp
• Docs: Qué puede hacer MCP con cada tipo de archivo
• Docs: No me puedo conectar: 401 / encabezado Authorization