Errores de API de IA: clave inválida, sin saldo, 429 y 500

Error 401: mi clave de API no funciona

Por qué pasa

La clave está mal copiada (con un espacio o un salto de línea), fue revocada, es de otro proveedor o va en la cabecera equivocada.

Cómo se arregla

1. Copia la clave de nuevo desde la consola del proveedor, sin espacios al principio ni al final.
2. Si la lees de una variable de entorno, comprueba que tiene valor en esa terminal.
3. Revisa la cabecera: la mayoría usan Authorization: Bearer <clave>; la API de Anthropic usa x-api-key.
4. Comprueba que la clave es del proveedor al que llamas y que no está desactivada en su consola.
5. Si dudas, crea una clave nueva y borra la antigua.

La API dice que no tengo saldo, pero pago ChatGPT Plus o Claude Pro

Por qué pasa

La suscripción del chat y la API se pagan por separado. Pagar el plan del chat no da crédito para la API. En OpenAI, la falta de saldo llega como un error 429 con el aviso «insufficient_quota».

Cómo se arregla

1. Entra en la consola de desarrolladores del proveedor (no en la web del chat).
2. Añade un método de pago o crédito.
3. Pon un límite de gasto mensual antes de lanzar nada.
4. Si la clave es anterior al pago, prueba con una clave nueva.

Error 429: Too Many Requests al usar la API

Por qué pasa

Has superado el límite de peticiones o de tokens por minuto de tu cuenta. Los límites dependen del proveedor, del modelo y de tu nivel de uso.

Cómo se arregla

1. Espera y reintenta, aumentando la espera cada vez (1, 2, 4, 8 segundos…).
2. Si la respuesta trae la cabecera Retry-After, espera ese tiempo.
3. Baja el número de peticiones en paralelo.
4. Agrupa trabajo: una petición con diez textos en lugar de diez peticiones.
5. Pon un tope de reintentos para no quedarte en bucle.

La API de IA devuelve 500, 502, 503 o «overloaded»

Por qué pasa

Son fallos temporales del proveedor o de un intermediario: el servidor está saturado o ha fallado. La API de Anthropic usa además el código 529 para «sobrecargado». No es culpa de tu petición.

Cómo se arregla

1. Reintenta tras unos segundos, con espera creciente y un tope de intentos.
2. Mira la página de estado del proveedor.
3. Si es crítico, prepara un modelo o proveedor de respaldo.
4. Guarda lo ya procesado para no repetirlo todo al reintentar.

Mi automatización con IA dejó de funcionar de repente: «token expired»

Por qué pasa

Los tokens de inicio de sesión caducan, y las claves pueden revocarse. Si la automatización usa la sesión de tu navegador o de tu terminal, un día deja de valer.

Cómo se arregla

1. Mira el registro de la automatización: el error suele decir «expired», «revoked» o 401.
2. Para lo que corre solo, usa una clave de API o un token de larga duración, no tu sesión personal.
3. Apunta cuándo caduca y ponte un aviso antes.
4. Haz que la automatización avise cuando falle, en lugar de fallar en silencio.

La API corta la respuesta y dice «length» o «max_tokens»

Por qué pasa

La respuesta llegó al número máximo de tokens que pediste (o al que pone el programa por defecto).

Cómo se arregla

1. Sube el parámetro de tokens máximos de la respuesta.
2. Pide la salida por partes.
3. Con modelos que razonan, recuerda que el razonamiento también gasta de ese máximo.
4. Comprueba siempre el motivo de fin de cada respuesta en tu código antes de usarla.

Pido JSON a la API y a veces me devuelve texto o JSON roto

Por qué pasa

Si solo se lo pides con palabras, el modelo puede añadir explicaciones, envolverlo en un bloque de código o cortarlo a la mitad.

Cómo se arregla

1. Usa el modo de salida JSON o estructurada del proveedor, si existe.
2. Valida el JSON en tu código y, si falla, reintenta una vez.
3. Quita los marcadores de bloque de código antes de leerlo.
4. Si el contenido llega vacío, que tu programa falle con un mensaje claro en vez de guardar una fila en blanco.

Guía: respuestas vacías y JSON en Ollama

La factura de la API de IA es mucho más alta de lo que esperaba

Por qué pasa

En un chat, cada mensaje vuelve a enviar todo el historial, así que el coste crece con la conversación. Los modelos que razonan cobran también esos tokens, y algunos programas usan un segundo modelo para tareas como poner títulos.

Cómo se arregla

1. Pon un límite de gasto mensual en la consola del proveedor.
2. Revisa el uso por modelo: a veces el gasto viene de uno que no sabías que se usaba.
3. Usa un modelo barato para lo sencillo y el caro solo para lo que lo necesite.
4. Recorta el historial que reenvías en cada petición.

Guía: el segundo modelo de OpenCode (small_model)