Códigos de error

El code de cada error de la respuesta (errors[].code) y el código HTTP con el que llega. Salen de resources/exceptions.py y resources/handlers.py, que tai-api init copia al proyecto.

code	HTTP	Qué significa	Qué hace el cliente
VALIDATION_ERROR	422	Un parámetro, un campo o una operación que no vale; hay un error por campo, con field. También, con X-Tai-Strict: 1, lo que la API ignoraría: un parámetro, un order_by o un includes que no existen	Enseñarlo en el formulario (fieldErrors)
INVALID_INPUT	400	Una petición mal formada
MISSING_REQUIRED_FIELD	400	Falta un campo obligatorio
BUSINESS_RULE_VIOLATION	422	Una regla de negocio: un trigger de tai-sql que la detuvo con t.abort(mensaje) —el mensaje es el suyo—, o un endpoint propio con BusinessRuleViolationException	Enseñar el mensaje
RECORD_NOT_FOUND	404	No existe, o el RLS no deja verlo; en una escritura anidada, una fila hija que no existe, no se alcanza o es de otro padre (con field)
DUPLICATE_RECORD	409	Viola una restricción de unicidad
FOREIGN_KEY_VIOLATION	409	Apunta a algo que no existe, o se borra algo de lo que otros dependen
UNAUTHORIZED_ACCESS	401	Sin token, o sin sesión que refrescar	Al login
INVALID_CREDENTIALS	401	Usuario o contraseña incorrectos —sin decir cuál de los dos, para no revelar qué usuarios existen—, cuenta deshabilitada o contraseña caducada	Enseñar el mensaje
INVALID_TOKEN	401	Un token manipulado, de otro emisor o de un realm que la API no acepta	Al login
TOKEN_EXPIRED	401	El access token ha caducado	Refrescar y reintentar
SESSION_INVALIDATED	401	La sesión se cerró: reason: "concurrent_login" (otro dispositivo) o "refresh_reused" (por seguridad)	Al login, con el motivo
SESSION_EXPIRED	401	La sesión caducó por inactividad o por su límite	Al login
CONCURRENT_SESSION_DETECTED	409	Reservado; tai-api no lo emite hoy
INSUFFICIENT_PERMISSIONS	403	Con token válido, sin el permiso que pide el endpoint (details.required_permission), también el de una tabla hija en una escritura anidada (con field); con owner(), una fila que no sería del usuario (details.reason: "OWNER"); o sin la cabecera X-Tai-Client en la sesión con cookie	Enseñar que no tiene permiso
DATABASE_ERROR	500	Un fallo de la base de datos; el detalle va al log
INTERNAL_SERVER_ERROR	500	Un fallo del servidor; el detalle va al log
SERVICE_UNAVAILABLE	503	Keycloak o la base de datos no responden	Reintentar más tarde
TIMEOUT_ERROR	504	Una dependencia no respondió a tiempo	Reintentar más tarde

resources/ no se regenera

tai-api init copia resources/ al proyecto una vez, y generate no lo toca: es la única parte que tai-api entrega y abandona. Un código que añada una versión nueva no llega a los proyectos existentes, y por eso ningún endpoint generado depende de uno que no estuviera ya. Lo que sí hace generate es avisar si el resources/ del proyecto es de una revisión anterior a la del paquete, y decir qué trae la nueva: ver El proyecto por dentro.

Errores del CLI

Los comandos de tai-api cuentan un problema con un mensaje, su solución y un código estable, con el prefijo A:

Código	Nombre	Cuándo
A001	PROJECT_NOT_FOUND	No se encuentra el .taiapiproject, o el proyecto de tai-sql
A002	PROJECT_FILE_INVALID	El .taiapiproject no se puede leer, o tiene una clave que no existe
A010	AUTH_NOT_CONFIGURED	El comando necesita autenticación y no hay: tai-api auth init
A011	REALM_NOT_FOUND	Un realm que no está en la configuración
A012	INVALID_OPTION	Una opción o un valor que no vale; también un bloque frontend que activa algo (react, svelte, zod) que el package.json del frontend no tiene
A020	RBAC_DEFINITION	Un error en rbac/<realm>.py
A021	RBAC_NOT_FOUND	No hay rbac/<realm>.py para el realm
A030	BACKEND_FAILED	Keycloak o la base de datos de auth fallan
A031	UNSAFE_OPERATION	Una operación que borraría algo con usuarios, sin confirmar
A040	GENERATION_FAILED	La generación falla
A041	GENERATED_OUTDATED	Lo generado ya no corresponde a la configuración (un secret_key_name cambiado): tai-api generate