Errores y solución de problemas

Diagnostica fallos de conexión, entrada y recuperación antes de reintentar.

Lee la respuesta de error

Los fallos de herramientas HTTP normalmente devuelven error con code, message y traceId; los errores de validación pueden incluir details. Revisa también el estado HTTP. Los proxies y límites de tamaño pueden devolver otro formato; los clientes de producción deben manejar respuestas no JSON. Registra herramienta, hora, ID del job y traceId para diagnóstico, eliminando credenciales y URLs privadas de medios.

json

{
  "error": {
    "code": "INVALID_JSON",
    "message": "Malformed JSON",
    "traceId": "<diagnostic-id>"
  }
}

Fallos comunes

Señal	Solución
401 · UNAUTHORIZED	Revisa la clave del espacio de trabajo y el encabezado Bearer, no el login del sitio ni la clave del proveedor.
403 · FORBIDDEN	Revisa permisos read/write/admin, propiedad y reglas de origen del navegador.
404 · NOT_FOUND	Revisa nombre de herramienta, versión instalada y cuenta propietaria del registro.
400 · INVALID_JSON	Envía JSON válido con el tipo de contenido correcto.
UPLOAD_EXPIRED / UPLOAD_MISMATCH	Crea una nueva intención si venció; de lo contrario, revisa bytes y SHA-256 del archivo exacto.
REVISION_CONFLICT	Lee el snapshot actual y reaplica la edición sin sobrescribir trabajo más reciente.
413	Reduce el cuerpo. Usa la ruta de subida binaria para recursos, no un argumento base64.

Reglas de reintento

Reintenta lecturas con una espera acotada ante fallos temporales de red. Para una mutación con respuesta incierta, recupera primero el job o la solicitud guardada. Reutiliza la clave de idempotencia solo para la misma operación y contenido. Cambiar el brief, modelo o referencia exige una nueva preparación. Una conexión interrumpida no significa que se canceló el trabajo del proveedor.

Cuando un modelo no está disponible

Vuelve a leer capabilities y revisa disponibilidad, modo de entrada y requisitos faltantes. Un perfil en el catálogo no demuestra que la clave, el saldo o las referencias estén listos. Mantén explícita la selección; no cambies de proveedor, elimines referencias ni pases a texto a video sin informar. Si falta una función en el paquete instalado, consulta la guía de esa versión o actualiza por el procedimiento admitido.

Referencia de rikoko 0.1.30, revisada el 21 de octubre de 2026. El instalador público tiene su propia versión; consulta los parámetros y modelos de tu instalación.