Códigos de salida

El CLI tecsas3-cli usa exit codes estables para que los orquestadores (systemd, GitHub Actions, Airflow, cron, scripts bash) puedan enrutar errores sin parsear stderr. Cada subclase de TecsaError define su propio exit_code y el handler central en cli/src/tecsas3_cli/cli.py:run() los traduce a sys.exit(...). El rango 0–5 se reserva para clases de error conocidas y predecibles; el 99 absorbe cualquier excepción no esperada.

Tabla de exit codes

Exit	Clase de error	Cuándo se emite	HTTP equivalente
`0`	(éxito)	El comando terminó correctamente. `typer.Exit(0)` o retorno normal.	`2xx`
`1`	`NotFoundError`, `ValidationError`, `TecsaError` base	Recurso inexistente (`404`), validación del backend (`400`–`499` distintos de 401/403/404), o error genérico del CLI.	`404`, `400`–`499`
`2`	`ServerError`	Cualquier `5xx` devuelto por el backend tras los reintentos automáticos (2 intentos con backoff 0.5s/1s).	`500`, `502`, `503`, `504`
`3`	`AuthError`	Token expirado o ausente (`401`), permisos insuficientes (`403`), o `LOGIN_FAILED` al autenticarse.	`401`, `403`
`4`	`ConfigError`	`base_url` no es HTTPS, falta `tenant` para rutas protegidas, TOML malformado, directorio sin permisos.	—
`5`	`NetworkError`	Timeout, DNS failure, TLS handshake, conexión rechazada. Sin respuesta HTTP.	—
`99`	`UNEXPECTED` (catch-all en `run()`)	Cualquier `Exception` no controlada; el stack va a `stderr` con `code=UNEXPECTED`.	—

La asignación anterior es la implementada en cli/src/tecsas3_cli/errors.py y en el handler run() de cli/src/tecsas3_cli/cli.py. Los códigos 0 y 1 son los únicos compartidos por varias clases: NotFoundError y ValidationError colapsan a 1 para simplificar el branching en shell (if ! tecsas3 ...; then ...).

Mapeo desde HTTP status

El factory from_http_status(status, message, ...) centraliza la conversión. Cualquier 4xx/5xx que llegue del backend se traduce a la subclase apropiada y conserva http_status, hint y request_id para diagnóstico.

HTTP	Clase	Exit code	Hint automático
`400`–`499` (excepto 401/403/404)	`ValidationError`	`1`	—
`401`, `403`	`AuthError`	`3`	`Verifica tu token (tecsas3 auth login) y el tenant activo.`
`404`	`NotFoundError`	`1`	`Verifica el ID o usa 'tecsas3 <resource> list' para ver disponibles.`
`500`+	`ServerError`	`2`	`Error del backend. Reintenta o contacta a soporte con el request_id.`

Ejemplos por exit code

# Exit 0 — éxito.
tecsas3 --json --no-input ping
echo "exit=$?"   # 0

# Exit 1 — NotFoundError.
tecsas3 --json --no-input paciente get 999999
# ERROR [NOT_FOUND] Paciente 999999 no encontrado.
# Sugerencia: Verifica el ID o usa 'tecsas3 paciente list' para ver disponibles.
echo "exit=$?"   # 1

# Exit 1 — ValidationError.
tecsas3 --json --no-input paciente create --data '{"cedula": ""}'
# ERROR [VALIDATION_ERROR] cedula: este campo es obligatorio.
echo "exit=$?"   # 1

# Exit 2 — ServerError tras 2 reintentos.
tecsas3 --json --no-input dashboard resumen
# ERROR [SERVER_ERROR] Internal server error (request_id=abc-123).
# Sugerencia: Error del backend. Reintenta o contacta a soporte con el request_id.
echo "exit=$?"   # 2

# Exit 3 — AuthError (token expirado).
tecsas3 --json --no-input paciente list
# ERROR [AUTH_ERROR] Token inválido o expirado (http_status=401).
# Sugerencia: Verifica tu token (tecsas3 auth login) y el tenant activo.
echo "exit=$?"   # 3

# Exit 4 — ConfigError (base_url http sin localhost).
tecsas3 --base-url http://api.tecsas3.com paciente list
# ERROR [CONFIG_ERROR] base_url 'http://api.tecsas3.com' usa HTTP sin cifrar.
echo "exit=$?"   # 4

# Exit 5 — NetworkError (timeout).
tecsas3 --json --no-input --timeout 0.1 agente heatmap
# ERROR [NETWORK_ERROR] Timeout llamando GET /agente/api/heatmap/: ...
echo "exit=$?"   # 5

# Exit 99 — UNEXPECTED.
tecsas3 --json --no-input --debug paciente list   # bug hipotético
# ERROR [UNEXPECTED] KeyError: 'campo_inexistente'
# Sugerencia: Ejecuta con --debug.
echo "exit=$?"   # 99

Patrones de scripting

Branching simple por éxito / fallo

if tecsas3 --json --no-input paciente list > /tmp/p.json; then
  echo "OK: $(jq 'length' /tmp/p.json) pacientes."
else
  rc=$?
  echo "Fallo con exit=$rc" >&2
  exit $rc
fi

Reintentos sólo en `ServerError` (exit 2)

for i in 1 2 3; do
  tecsas3 --json --no-input dashboard resumen && break
  rc=$?
  if [ "$rc" -ne 2 ]; then
    echo "Fallo no recuperable: $rc" >&2
    exit "$rc"
  fi
  sleep $((i * 5))
done

Enrutamiento por tipo de error en CI

# .github/workflows/ci.yml (fragmento)
- name: Sync FHIR bundle
  id: fhir
  run: tecsas3 --json --no-input fhir export-bundle
  continue-on-error: true
- name: Classify failure
  if: steps.fhir.outcome == 'failure'
  run: |
    case "${{ steps.fhir.outputs.exit_code }}" in
      3) echo "::error::AuthError — re-login required" ;;
      4) echo "::error::ConfigError — fix config.toml"   ;;
      5) echo "::warning::NetworkError — re-run later"  ;;
      *) echo "::error::Unexpected (${{ steps.fhir.outputs.exit_code }})" ;;
    esac

Inspección del error completo

Con --json, los errores se serializan con todos los campos de diagnóstico:

$ tecsas3 --json --no-input paciente get 999999
{"error": {
  "code": "NOT_FOUND",
  "message": "Paciente 999999 no encontrado.",
  "http_status": 404,
  "hint": "Verifica el ID o usa 'tecsas3 paciente list' para ver disponibles."
}}

request_id aparece cuando el backend lo emite en X-Request-ID y permite correlación con los logs del servidor.

Troubleshooting

Exit code inesperado en pipes

# ¡OJO! `pipefail` cambia el exit del último comando de la pipeline.
set -o pipefail
tecsas3 --json --no-input paciente list | jq '.results'
echo "exit=$?"   # ahora refleja el primer fallo, no el de jq

Si quieres el comportamiento clásico (exit del último comando), quita pipefail o usa:

tecsas3 --json --no-input paciente list > /tmp/p.json
rc=$?
jq '.results' /tmp/p.json
exit $rc

Exit 2 persistente tras reintentos

ServerError ya incluye 2 reintentos con backoff 0.5s/1s. Si el backend sigue 5xx tras 3 intentos totales, el CLI emite exit 2. Posibles causas:

Caída real del servicio — revisa el dashboard de salud del tenant.
Mantenimiento programado — espera la ventana y reintenta más tarde.
Bug reproducible — captura el request_id y repórtalo a soporte.

# Inspección del request_id.
tecsas3 --json --no-input dashboard resumen 2>&1 | jq -r '.error.request_id'
# abc-123-def-456

El login fue OK pero el siguiente comando falla con 401. Causa típica: el backend invalida tokens emitidos con un SECRET_KEY distinto al actual (rotación de claves o reinicio de entorno). Solución:

# Re-login limpio.
tecsas3 auth logout
tecsas3 auth login --user ana@eps.example --password "$PWD"

Exit 4 (`ConfigError`) con TOML válido

load_settings ignora silenciosamente secciones [profile.<x>] que no parsean. Verifica que el perfil que estás invocando existe:

tecsas3 config list
# demo: https://dev.tecsas3.com
# prod: https://api.tecsas3.com

tecsas3 --profile demo config show

Exit 5 (`NetworkError`) sólo en CI

El runner no tiene acceso al backend (firewall corporativo, NAT, DNS privado). Diagnóstico:

# Ping TCP al backend.
nc -zv api.tecsas3.com 443

# DNS.
dig +short api.tecsas3.com

# Si todo OK pero el CLI falla, prueba con timeout alto.
tecsas3 --timeout 60 --json --no-input ping

Exit 99 con stacktrace verboso

El handler run() imprime code=UNEXPECTED y la excepción cruda a stderr. Para reportarlo:

# Capturar el stack completo.
tecsas3 --debug --json --no-input <comando> 2> /tmp/tecsas3.crash
# Adjuntar /tmp/tecsas3.crash al ticket de soporte (sin credenciales).

Siguientes pasos

Profundiza en la redacción PHI que se aplica a stderr en modo --debug.
Aprende a fijar el formato de salida por defecto.
Revisa la configuración para validar base_url y tenant antes de correr scripts largos.

Empezar

Conceptos

Guías

Soporte

Tabla de exit codes

Mapeo desde HTTP status

Ejemplos por exit code

Patrones de scripting

Branching simple por éxito / fallo

Reintentos sólo en `ServerError` (exit 2)

Enrutamiento por tipo de error en CI

Inspección del error completo

Troubleshooting

Exit code inesperado en pipes

Exit 2 persistente tras reintentos

Exit 4 (`ConfigError`) con TOML válido

Exit 5 (`NetworkError`) sólo en CI

Exit 99 con stacktrace verboso

Siguientes pasos

​Tabla de exit codes

​Mapeo desde HTTP status

​Ejemplos por exit code

​Patrones de scripting

​Branching simple por éxito / fallo

​Reintentos sólo en ServerError (exit 2)

​Enrutamiento por tipo de error en CI

​Inspección del error completo

​Troubleshooting

​Exit code inesperado en pipes

​Exit 2 persistente tras reintentos

​Exit 3 (AuthError) inmediato tras login

​Exit 4 (ConfigError) con TOML válido

​Exit 5 (NetworkError) sólo en CI

​Exit 99 con stacktrace verboso

​Siguientes pasos

Tabla de exit codes

Mapeo desde HTTP status

Ejemplos por exit code

Patrones de scripting

Branching simple por éxito / fallo

Reintentos sólo en `ServerError` (exit 2)

Enrutamiento por tipo de error en CI

Inspección del error completo

Troubleshooting

Exit code inesperado en pipes

Exit 2 persistente tras reintentos

Exit 3 (`AuthError`) inmediato tras login

Exit 4 (`ConfigError`) con TOML válido

Exit 5 (`NetworkError`) sólo en CI

Exit 99 con stacktrace verboso

Siguientes pasos