# Guion del vídeo, para comentar o para lo que necesites.
# Es una PROYECCIÓN del nuestro: lleva el contenido —qué se dice, qué se ve, en
# qué orden y cuánto dura— y no la maquinaria que lo convierte en vídeo.
id: productos-estados-errores
title: 'Manejo de estados y errores: el sobre uniforme'
audience: Desarrollador que va a escribir el manejo de errores de su integración
objetivo: >
  Al terminar, el espectador programa contra el sobre de error en vez de adivinar, sabe qué hacer
  con cada código, y se lleva tres cosas que se descubren tarde: un 409 no se reintenta igual, un
  recurso ajeno devuelve 404 y no 403, y la validación corre antes que la autenticación.
cta: 'Siguiente: ''Ciclo de vida de la sesión'' o ''Estados y contrato de error''.'
target_duration_s: 141
storyboard:
  - 'n': 1
    on_screen: Un solo sobre para todos los errores
    narracion: >-
      La API responde todos sus errores con el mismo sobre JSON, y programar contra ese sobre te
      evita parsear HTML o adivinar. Trae tres campos: un indicador de éxito que en un error siempre
      viene en falso, un mensaje legible para diagnosticar, y un código estable.
    visual: Distintos errores llegando todos con la misma forma de sobre.
    duracion_s: 18
  - 'n': 2
    on_screen: Ramifica por el código, no por el mensaje
    narracion: >-
      Y conviene usarlos para lo que son. El mensaje es para que tú diagnostiques: no se lo muestres
      tal cual a tu usuario final. Lo que usas para ramificar tu lógica es el código, porque es el
      que se mantiene estable.
    visual: El mensaje marcado como diagnóstico interno, y el código como aquello por lo que se ramifica.
    duracion_s: 16
  - 'n': 3
    on_screen: Qué hacer con cada uno
    narracion: >-
      Los que vas a ver a diario son cuatro. Un cuatrocientos dice que el cuerpo no cumple el
      contrato: corriges el payload. Un cuatrocientos uno, que falta el Bearer o no vale:
      reautenticas. Un cuatrocientos cuatro, que el recurso no existe. Y un cuatrocientos veintidós,
      que el cuerpo está bien formado pero el objeto que referencia no vale — ahí revisa los
      identificadores que enviaste, no el formato.
    visual: Los códigos habituales, cada uno con la acción que le corresponde.
    duracion_s: 26
  - 'n': 4
    on_screen: Un 409 no se reintenta igual
    narracion: >-
      Y uno que merece su propia advertencia: el cuatrocientos nueve, que dice que el recurso existe
      y choca — un correo ya registrado, o una operación que no cabe en el estado actual. No lo
      reintentes igual: reintentar un cuatrocientos nueve da otro cuatrocientos nueve. Para el
      cuatrocientos veintinueve y el quinientos sí, reintenta, pero con espera creciente.
    visual: Un reintento idéntico de un 409 devolviendo otro 409, en bucle.
    duracion_s: 22
  - 'n': 5
    on_screen: Lo ajeno devuelve 404, no 403
    narracion: >-
      Otra que conviene conocer antes de depurar a ciegas: consultar una sesión de otra cuenta
      devuelve cuatrocientos cuatro, no cuatrocientos tres. Es deliberado: nunca revelamos la
      existencia de recursos ajenos. Así que si te da no encontrado y juras que ese identificador
      existe, comprueba con qué token estás llamando.
    visual: Un recurso ajeno respondiendo 404 en vez de 403, sin revelar que existe.
    duracion_s: 19
  - 'n': 6
    on_screen: La validación corre antes que la auth
    narracion: >-
      Y una que desconcierta al probar: en un POST, la validación del cuerpo corre antes que la
      autenticación. Un cuerpo inválido sin Bearer devuelve cuatrocientos, no cuatrocientos uno. Si
      lo que quieres es ver el cuatrocientos uno, usa una ruta protegida sin cuerpo, o manda un
      cuerpo válido sin la cabecera.
    visual: En un POST, la validación corriendo antes que la autenticación.
    duracion_s: 20
  - 'n': 7
    on_screen: Y no confundas error con estado
    narracion: >-
      Por último, la distinción que ordena todo esto: un error es que la llamada falló. Un estado es
      el desenlace de un pago. Que una sesión venga pagada, fallida o vencida son respuestas
      exitosas que describen qué pasó — no son errores, y no van por el mismo camino en tu código.
    visual: Cierre de marca; un error y un estado, claramente separados.
    duracion_s: 20