Objetivos
- Leer un mensaje de error sin miedo: encontrar la línea que importa y entender qué dice.
- Saber qué significan 401, 403, 404, 422, 429 y 500 y qué comprobar primero en cada caso.
- Preguntar bien a una IA con el prompt de emergencia: contexto primero, error completo, sin claves.
- Actuar en orden si publicas una clave: revocar en el proveedor primero, limpiar después.
- Guardar tu trabajo con Git (init, add, commit, push) y subirlo a GitHub sin subir nunca el .env.
Antes de empezar: pe05 (tu API en local) y la cuenta de GitHub de pe02.
Prompt de arranque
Esta unidad no empieza con un prompt que genera código, sino con el que vas a usar cada vez que algo falle: el prompt de emergencia. Guárdalo en tus notas:
Estoy aprendiendo y no sé programar. Te doy el contexto antes del error. Qué quería hacer: [una frase, por ejemplo: preguntar a mi API de FastAPI] Qué esperaba: [por ejemplo: una respuesta de Gemini con código 200] Qué ha pasado: [por ejemplo: sale "Internal Server Error"] Mi sistema: [Windows 11 / macOS / Ubuntu] · Python [versión] · uso uv Comando que ejecuté: [cópialo exacto] Error completo (sin claves ni contraseñas): [pega el traceback ENTERO, de la primera a la última línea] Lo que ya he probado: [por ejemplo: reiniciar la API] Explícame en dos frases qué significa el error. Después dame UN solo cambio para probar y cómo compruebo si ha funcionado. No reescribas todo el proyecto.
Esto lo escribe la IA, tú compruebas que funciona. La IA propone un arreglo; tú lo pruebas, miras el resultado y, si no funciona, vuelves con el error nuevo.
Explicación
Los errores no son fracasos, son mensajes
Cuando algo sale en rojo, el instinto es pensar «lo he roto todo». Casi nunca es así. Un error es el ordenador diciéndote, con su vocabulario raro, exactamente qué le ha faltado. Es como el testigo del coche: la luz del aceite no significa que el motor haya explotado, significa «mira el aceite». Quien programa a diario no comete menos errores que tú: simplemente sabe leer los testigos.
Cómo leer un error de Python: de abajo arriba
Cuando Python falla, escribe un traceback: el recorrido que hizo el programa hasta tropezar. Se lee de abajo arriba:
- La última línea es la importante: tipo de error y explicación.
AttributeError: 'GenerateContentResponse' object has no attribute 'texto'. Did you mean: 'text'?te dice qué pasa y hasta te sugiere el arreglo. - Sube buscando tu fichero. Entre muchas líneas de librerías, busca la que menciona
main.py: te dice en qué línea de tu código empezó el problema. - Ignora lo demás la primera vez. Las líneas de en medio son el camino por dentro de las librerías; sirven a la IA, no a ti para entender qué pasa.
Los tipos que más verás al principio: ModuleNotFoundError (falta instalar algo o no estás en el entorno), SyntaxError (falta un paréntesis o unas comillas), AttributeError y KeyError (pides un dato con un nombre que no existe), FileNotFoundError (ruta equivocada) y los errores de conexión.
Los códigos HTTP: el semáforo de las APIs
Cada respuesta de una API (la tuya o la de Google) trae un número de tres cifras. Los que empiezan por 2 son buenos; por 4, el problema está en lo que tú enviaste; por 5, en el servidor.
| Código | Qué significa | Primera cosa que comprobar |
|---|---|---|
| 200 | Todo bien | Nada |
| 401 | «No sé quién eres»: falta la clave o es incorrecta | La clave de .env: bien copiada, sin espacios ni comillas, no revocada |
| 403 | «Sé quién eres, pero no puedes entrar aquí» | Permisos de tu cuenta para ese modelo o recurso; a veces, aceptar condiciones en la web del proveedor |
| 404 | «Eso no existe» | Erratas en la ruta (/preguntas) o un nombre de modelo retirado |
| 422 | «Lo que me envías no tiene el formato que espero» | El JSON: comillas, comas y nombres de campo |
| 429 | «Demasiadas peticiones, espera» | Esperar uno o dos minutos; revisar los límites gratuitos |
| 500 | «Algo ha fallado dentro del servidor» | Si el servidor es tuyo, la terminal donde corre la API: ahí está el traceback de verdad |
El 500 merece una nota: el navegador solo dirá Internal Server Error. El detalle útil está en la terminal del servidor, y esa es la que copias en el prompt de emergencia.
Buscar un error como un profesional
Antes de preguntar, busca. Copia la última línea del error, quita lo que sea tuyo (tu usuario en las rutas, tus ficheros) y búscala entre comillas añadiendo la herramienta: "Address already in use" fastapi. Casi seguro que alguien tuvo el mismo problema y la respuesta está en la documentación oficial, en los issues de GitHub del proyecto o en Stack Overflow. Mira la fecha: una respuesta de hace cinco años puede ya no servir.
Preguntar bien a una IA: prompt primero
La IA es tu mejor ayudante para errores, pero solo si le das contexto. El fallo típico es pegar tres líneas y escribir «no funciona»: la IA adivina, propone reescribir medio proyecto y lo deja peor. La regla es prompt primero: antes del error va qué querías, qué esperabas, qué pasó, tu sistema y lo que ya probaste. Después, el traceback completo.
Tres reglas que no se negocian:
- Nunca pegues claves. Revisa que el error no incluya tu
.env, una cabeceraAuthorizationni nada que empiece porAQ.,AIza,gsk_,sk-or-,sk-oghp_. Si aparece, cámbialo porXXXX. - Un solo cambio cada vez. Si aplicas cinco arreglos y funciona, no sabes cuál fue; si no funciona, no sabes cuál lo empeoró.
- Comprueba antes de seguir. Prueba, mira el resultado y vuelve con el error nuevo si lo hay.
Si publicas una clave: revocar primero
Si una clave llega a GitHub, a un chat, a una captura o a un vídeo, considérala robada: hay programas que recorren GitHub buscando claves y las usan en minutos. El orden importa:
- Revoca la clave en la web del proveedor y crea una nueva. Esto va antes que nada.
- **Pon la nueva en
.env** y comprueba que.envestá en.gitignore. - Limpia el repositorio. Borrar el fichero en un commit nuevo no basta: la clave sigue en las fotos anteriores. Si el repositorio es tuyo y pequeño, lo más sencillo es borrarlo en GitHub y crearlo de nuevo.
GitHub tiene «push protection», que bloquea muchos formatos de clave conocidos al subir a repositorios públicos. Ayuda, pero no lo detecta todo.
Git: el botón de guardar partida
Si mañana la IA rompe tu API, ahora mismo no tienes forma de volver atrás. Git guarda «fotos» (commits) de tu proyecto, como guardar partida antes del jefe final. GitHub es la copia de esas partidas en la nube.
git status: qué ha cambiado desde la última foto.git add: elegir qué entra en la foto.git commit -m "mensaje": hacer la foto con una frase que explique el cambio.git push: subir las fotos a GitHub.git diffygit restore: ver qué cambió y deshacer lo que aún no está en una foto.
Sorpresa útil: uv init ya ejecutó git init en pe05, así que mi-api ya es un repositorio. Pero el .gitignore que crea uv **no incluye .env**: con un git add . sin arreglarlo, tu clave entraría en la foto.
Tu diario de builder
Crea DIARIO.md en tu proyecto y apunta cada error que resuelvas en tres líneas: síntoma, causa y arreglo. En un mes tendrás tu propio manual.
Lab paso a paso
Objetivo: provocar y resolver a propósito cuatro errores en tu API de pe05, simular una clave publicada y dejar el proyecto en GitHub sin el .env.
Parte 1. Provocar y resolver errores
Arranca la API (cd ~/lab/mi-api y uv run fastapi dev main.py) y abre http://127.0.0.1:8000/docs. Apunta cada caso en DIARIO.md.
1401, clave mal. En .env, cambia una letra de la clave. Ctrl+C y arranca de nuevo. Pregunta algo en /docs: Code 401 y «Google ha rechazado tu clave». Deshaz el cambio y reinicia.
2404, dos variantes. Abre http://127.0.0.1:8000/preguntas: {"detail":"Not Found"}. Después añade a .env la línea MODELO=gemini-que-no-existe, reinicia y pregunta: tu API responde 404 «El modelo … no existe». Borra esa línea y reinicia.
3429, demasiadas peticiones. Lanza 20 preguntas seguidas. Consume unas 20 peticiones de tu cuota diaria; si no aparece ningún 429, tu límite por minuto es más alto y basta con saber reconocerlo.
macOS y Linux:
for i in $(seq 1 20); do curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8000/preguntar -H "Content-Type: application/json" -d '{"pregunta": "Di hola"}'; done
Windows (PowerShell):
1..20 | ForEach-Object { try { Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/preguntar -ContentType "application/json" -Body '{"pregunta": "Di hola"}' | Out-Null; "200" } catch { [int]$_.Exception.Response.StatusCode } }
Salida esperada: varias líneas 200 y, cuando se supera el límite por minuto, 429. Espera un minuto y comprueba que vuelve el 200.
4500 con traceback. En main.py, cambia respuesta.text por respuesta.texto y guarda (fastapi dev reinicia solo). Pregunta algo: el navegador dice Internal Server Error. Ve a la terminal del servidor: al final verás AttributeError: 'GenerateContentResponse' object has no attribute 'texto'. Did you mean: 'text'?. Sube hasta la línea que menciona main.py.
5Prompt de emergencia. Copia ese traceback en el prompt de emergencia y pégalo en un chat de IA. Comprueba que propone volver a respuesta.text, aplícalo y verifica el 200.
Parte 2. Simulacro de clave publicada y revocación
No publiques nada real. El simulacro es encontrar y revocar:
1En AI Studio, crea una clave nueva llamada simulacro-pe06 (https://aistudio.google.com/apikey).
2Imagina que la has pegado en un chat. Aplica el orden: en la misma página, borra la clave simulacro-pe06. Comprueba que desaparece de la lista.
3Localiza el botón equivalente en los otros proveedores de pe02, aunque no borres nada: https://console.groq.com/keys (icono de papelera junto a cada clave) y https://openrouter.ai/settings/keys (menú de la clave, borrar o desactivar).
4Busca si alguna foto de Git contiene algo con forma de clave (hazlo de nuevo tras la parte 4):
git log -p | grep -E "AQ\.|AIza|gsk_|sk-or-"
En Windows: git log -p | Select-String "AQ\.|AIza|gsk_|sk-or-". Si no sale nada, ningún commit contiene una clave.
Parte 3. Instalar la herramienta de GitHub (gh)
| Sistema | Comando |
|---|---|
| Windows (PowerShell) | winget install --id GitHub.cli -e y reabre PowerShell |
| macOS | brew install gh |
| Ubuntu | sudo apt update y sudo apt install -y gh |
Comprueba: gh --version responde con un número de versión.
Parte 4. Proteger el .env y hacer la primera foto
Desde ~/lab/mi-api (igual en los tres sistemas):
git status
Entre los ficheros nuevos aparece .env: es la alarma. Abre .gitignore en VS Code y añade al final:
# Secretos: nunca a Git
.env
*.log
Guarda y comprueba:
git check-ignore -v .env
git status
Salida esperada: .gitignore:13:.env .env (el número de línea puede variar) y .env ya no aparece en git status. Si git check-ignore no responde nada, .env no está ignorado.
Si es tu primera vez con Git en este ordenador:
git config --global user.name "Tu Nombre"
git config --global user.email "[email protected]"
La primera foto:
git add .
git commit -m "Primera versión de mi API con /saludo y /preguntar"
git log --oneline
git ls-files
git ls-files debe listar main.py, pyproject.toml, uv.lock, .gitignore, .python-version y README.md (con uv 0.13 o posterior, también src/mi_api/__init__.py), **nunca .env**.
Parte 5. Subir a GitHub
gh auth login
Responde GitHub.com → HTTPS → Y (autenticar Git con tus credenciales de GitHub) → Login with a web browser. Copia el código de un solo uso, pulsa Intro, pégalo en el navegador y autoriza. Después:
git branch -M main
gh repo create mi-api --private --source=. --push
Salida esperada: ✓ Created repository <tu-usuario>/mi-api on GitHub y ✓ Pushed commits to .... Ábrelo con gh repo view --web y comprueba que no está .env.
Parte 6. Volver atrás cuando la IA rompe algo
Borra la línea load_dotenv() de main.py y guarda. git diff la muestra en rojo con un -. git restore main.py la recupera. Regla: **commit antes de pedir a la IA un cambio grande; git diff después; git restore si no te convence.**
Ruta sin instalar nada: GitHub Codespaces
git y gh ya vienen instalados y con sesión iniciada: sáltate la parte 3 y gh auth login. Si el Codespace viene de un repositorio público, todo lo que subas será público: el .gitignore con .env es aún más importante.
Evidencia
DIARIO.mdcon los casos 401, 404, 429 (o «no apareció»), 500 y el simulacro de clave.- Captura de
git check-ignore -v .envrespondiendo. - Enlace o captura de tu repositorio
mi-apien GitHub, sin.env.
Criterio de aceptación
Checklist de seguridad de claves
- [ ]
.envestá en.gitignoreygit check-ignore -v .envresponde. - [ ]
git statusno muestra.envantes de cadagit add. - [ ] Ninguna clave escrita en el código: se lee con
os.getenv(...). - [ ] Lo que pegas en un chat no contiene
AQ.,AIza,gsk_,sk-or-,sk-,ghp_ni cabecerasAuthorization. - [ ] Capturas y grabaciones sin
.envni páginas de claves a la vista. - [ ] Una clave por proyecto, con nombre reconocible, para revocar solo esa.
- [ ] Ante la duda, revoca y crea otra: cuesta un minuto.
URLs de activación
Verificadas el 11-10-2026 (200 OK; Stack Overflow devuelve 403 a peticiones automáticas pero abre en el navegador).
| Para qué | URL oficial |
|---|---|
| Revocar o crear claves de Google AI Studio | https://aistudio.google.com/apikey |
| Revocar o crear claves de Groq | https://console.groq.com/keys |
| Revocar o crear claves de OpenRouter | https://openrouter.ai/settings/keys |
| Límites de la API de Gemini | https://ai.google.dev/gemini-api/docs/rate-limits |
Herramienta gh de GitHub | https://cli.github.com/ |
Ignorar ficheros con .gitignore (en español) | https://docs.github.com/es/get-started/git-basics/ignoring-files |
| Escaneo de secretos y push protection | https://docs.github.com/es/code-security/secret-scanning/introduction/about-secret-scanning |
| Libro oficial de Git (en español) | https://git-scm.com/book/es/v2 |
| Buscar errores ya resueltos | https://stackoverflow.com/ |
Errores frecuentes
| Síntoma | Qué pasa | Cómo se arregla |
|---|---|---|
ModuleNotFoundError: No module named 'google' (o fastapi, dotenv) | Ejecutas fuera del entorno del proyecto o falta la librería. | Entra en mi-api y usa uv run .... Si falta de verdad: uv add google-genai. Ojo: python-dotenv se importa como dotenv. |
Internal Server Error sin más detalle | El navegador nunca muestra el detalle de un 500. | Mira la terminal donde corre la API y lee el traceback de abajo arriba. |
| 401 aunque has cambiado la clave | El .env solo se lee al arrancar. | Ctrl+C y vuelve a arrancar. |
Author identity unknown *** Please tell me who you are. | Git no sabe tu nombre ni tu correo. | Las dos órdenes git config --global de la parte 4. |
warning: in the working copy of 'main.py', LF will be replaced by CRLF (Windows) | Windows termina las líneas con CRLF y macOS/Linux con LF. Es un aviso, no un error. | Ignóralo. Si vas a usar Docker o un servidor Linux (pe07), ejecuta una vez git config --global core.autocrlf input y elige «LF» en la barra inferior de VS Code. |
remote: Permission to ... denied o Authentication failed en git push | Git no tiene tus credenciales (GitHub no acepta la contraseña de la web). | gh auth login y elige autenticar Git con tus credenciales de GitHub. |
error: failed to push some refs ... (fetch first) | El repositorio de GitHub tiene algo que tú no (por ejemplo, un README creado en la web). | git pull --rebase origin main y git push. Para evitarlo, crea el repositorio con gh repo create. |
.env aparece en GitHub | Hiciste git add . antes de ignorarlo. | Revoca la clave ya. Después git rm --cached .env, commit y push. La clave sigue en el historial: por eso se revoca primero. |
Quiz
Cinco preguntas para comprobar que lo has entendido. Necesitas un 70 % para aprobar.