¿Tu API key no funciona? Soluciona 401, 402, 403 y 429
Por qué deja de funcionar una API key de IA: qué significan 401, 402, 403 y 429, qué código usa cada proveedor cuando se acaba el saldo y cómo resolverlo.
- Cuando una clave de API (API key) de IA «no funciona», el número del error te dice por qué: 401 significa que la clave en sí es incorrecta; 402 suele indicar que te quedaste sin saldo o sin créditos; 403, que la clave no tiene permiso para eso; y 429, demasiadas solicitudes o, con algunos proveedores, saldo agotado.
- Los proveedores no usan el mismo código para el saldo agotado. DeepSeek, OpenRouter, Mistral, Together, Fireworks y la facturación prepagada de Gemini usan 402; OpenAI, Kimi y Z.ai usan 429; Qwen, de Alibaba Cloud, usa 403. Lee el mensaje, no solo el número.
- Los errores de saldo no desaparecen si esperas; los límites de solicitudes, normalmente sí. La tabla de abajo indica la página oficial de errores de cada proveedor, revisada el 18 de noviembre de 2026.

¿Qué significa en realidad que una API key «no funciona»?
Una clave de API es el código secreto que una app envía con cada solicitud para que el proveedor de IA sepa que eres tú y a qué cuenta cobrar. Cuando algo sale mal, el proveedor responde con un error: un número de tres cifras llamado código de estado HTTP, más un mensaje corto.
El número indica qué tipo de problema es; el mensaje da el detalle. Oriveo convierte los más comunes en títulos claros, como «Clave API no válida» («API Key inválida» en la web) o «Cuota del proveedor agotada», que explicamos más abajo.
Guía rápida: 401, 402, 403, 429 y 5xx
Empieza aquí. Busca tu número y luego lee la sección correspondiente. Este resumen sigue las páginas de errores de OpenAI, Anthropic y otros proveedores a 18 de noviembre de 2026.
| Código | Qué suele significar | ¿Se arregla esperando? | Qué hacer |
|---|---|---|---|
| 401 | La clave es incorrecta: falta un carácter, sobra un espacio, la clave fue borrada o es de otro proveedor o región | No | Vuelve a copiar la clave o crea una nueva; revisa el proveedor y la región |
| 402 | Hace falta pagar: se acabó tu saldo prepagado o tus créditos, o hay un problema de facturación | No | Recarga saldo o corrige el método de pago en la página de facturación del proveedor |
| 403 | La clave funciona, pero no tiene permiso: país o región no admitidos, sin acceso a ese modelo o falta una verificación | No | Revisa las regiones admitidas, los permisos de la clave y cualquier verificación pendiente |
| 404 | El nombre del modelo o la dirección son incorrectos | No | Elige otro modelo o revisa la dirección |
| 429 | Demasiadas solicitudes en poco tiempo o, con algunos proveedores, saldo agotado o un límite de gasto | Muchas veces, si es un límite de solicitudes | Espera y reintenta; si el mensaje menciona quota, balance, credit o spend limit, recarga saldo o sube el límite |
| 500–504, 529 | Una falla o una sobrecarga del lado del proveedor | Normalmente sí | Inténtalo más tarde o cambia de modelo |
¿Por qué dice saldo insuficiente o cuota agotada?
La mayoría de los proveedores exigen crédito prepagado o un método de facturación activo para que la API funcione, y cada uno avisa del saldo agotado a su manera. Una clave nueva no arregla ninguno de estos casos; agregar crédito, sí.
Este es el código que documenta cada uno de los 15 proveedores integrados de Oriveo cuando se acaba tu saldo o tu crédito. «No se indica» significa que la documentación del proveedor, revisada el 18 de noviembre de 2026, no da un código HTTP para este caso.
| Proveedor | Código cuando se acaba el saldo | Qué dice el mensaje | Página oficial |
|---|---|---|---|
| OpenAI | 429 | credit_balance_exhausted (el tipo de error puede seguir diciendo insufficient_quota) | developers.openai.com/api/docs/guides/error-codes |
| Anthropic (Claude) | No se indica | «Your credit balance is too low to access the Anthropic API»; los problemas de pago devuelven 402 billing_error | platform.claude.com/docs/en/api/errors (códigos); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (mensaje) |
| Google Gemini | 402 (facturación prepagada) | payment_required; un 403 también puede indicar un saldo impago en Cloud Billing | aistudio.google.com/docs/api-errors |
| OpenRouter | 402 | «Your account or API key has insufficient credits» (créditos insuficientes en la cuenta o la clave) | openrouter.ai/docs/api-reference/errors |
| DeepSeek | 402 | Insufficient Balance | api-docs.deepseek.com/quick_start/error_codes |
| xAI (Grok) | No se indica | Las solicitudes se rechazan cuando se acaban los créditos prepagados | docs.x.ai/console/billing |
| Mistral AI | 402 | Payment required | docs.mistral.ai/resources/error-glossary |
| Groq | No documentado | Groq cobra después del uso; su página de errores no incluye ningún error de saldo | console.groq.com/docs/errors |
| Together AI | 402 | Payment Required | docs.together.ai/docs/error-codes |
| Fireworks AI | 402 | Payment Required | docs.fireworks.ai/guides/inference-error-codes |
| MiniMax | No se indica (código de negocio 1008) | insufficient balance | platform.minimax.io/docs/api-reference/errorcode |
| Z.ai (GLM) | 429 (código 1113) | Insufficient balance or no resource package. Please recharge. | docs.z.ai/api-reference/api-code |
| Qwen (Alibaba Cloud) | 403 | Arrearage o isv.OUT_OF_SERVICE (cuenta con deuda pendiente) | alibabacloud.com/help/en/model-studio/error-code |
| Kimi (Moonshot AI) | 429 | exceeded_current_quota_error | platform.kimi.ai/docs/api/errors |
| SiliconFlow | No documentado | No figura ningún error de saldo | docs.siliconflow.com/en/faqs/error-code |
401: API key no válida o error de autenticación
Un 401 significa que el proveedor no reconoce la clave. Los mensajes típicos son «Incorrect API key provided» (OpenAI), «authentication_error» (Anthropic), «Authentication Fails» (DeepSeek) e «Invalid API key: this is not an OpenRouter API key» (OpenRouter).
- Vuelve a copiar la clave desde el sitio del proveedor y revisa que no falten caracteres ni haya espacios al principio o al final.
- Asegúrate de que la clave sea del proveedor que elegiste. Una clave de OpenAI no funciona como clave de OpenRouter, ni al revés.
- Kimi, MiniMax y Qwen tienen plataformas regionales separadas, y una clave de una no funciona en otra. En Oriveo, elige la región que corresponde en el selector «Endpoint oficial» («URL de solicitud oficial» en iPhone).
- Si la clave fue borrada, revocada o venció, crea una nueva.
402: pago requerido o saldo insuficiente
Un 402 es cuestión de dinero: el saldo prepagado está vacío o falló el método de pago. Recarga o actualiza tus datos de pago en la página de facturación del proveedor y vuelve a enviar el mensaje. Esperar no sirve.
En Oriveo aparece como «Cuota del proveedor agotada»: «El proveedor indica que la cuota o el crédito de esta clave de API se agotó. Revisa tu facturación con el proveedor o cambia de modelo.»
403: acceso prohibido o permiso denegado
Un 403 significa que el proveedor reconoció la clave, pero no permite la solicitud. El motivo depende del proveedor:
- OpenAI devuelve «Country, region, or territory not supported» cuando la API se usa desde un país que no admite. Cada proveedor publica su lista de países admitidos.
- Gemini devuelve 403 cuando un proyecto del nivel gratuito necesita verificación (FREE_TIER_VERIFICATION_REQUIRED), cuando la cuenta de Cloud Billing vinculada tiene un saldo impago o cuando Google bloqueó una clave reportada como filtrada.
- Anthropic devuelve permission_error cuando la clave no puede usar ese recurso; revisa la configuración de tu organización y de tu workspace.
- OpenRouter devuelve 403 cuando una solicitud queda bloqueada por permisos, moderación, una regla de protección (guardrail) o un límite de presupuesto.
- SiliconFlow exige verificación de identidad para algunos modelos.
- Qwen usa 403 para una cuenta con deuda pendiente, y AllocationQuota.FreeTierOnly cuando se agotó la cuota gratuita y está activada la opción «Free Quota Only».
429: demasiadas solicitudes, límite de solicitudes o cuota superada
Casi siempre, 429 significa que enviaste demasiadas solicitudes o tokens en poco tiempo. Eso es un límite de solicitudes (rate limit), y se resuelve si esperas unas decenas de segundos. Si la respuesta incluye un tiempo Retry-After, espera ese tiempo.
Varios proveedores también usan 429 para el saldo agotado o un límite de gasto, y en esos casos esperar no sirve: OpenAI (credit_balance_exhausted, o un límite de gasto que configuraste), Kimi (exceeded_current_quota_error), Z.ai (código 1113) y Anthropic cuando una organización alcanza su límite de gasto mensual (enforced_spend_limit_reached), que dura hasta el mes siguiente salvo que solicites un nivel superior.
Los niveles gratuitos son más estrictos. El nivel gratuito de Gemini y los modelos gratis de OpenRouter tienen límites por minuto y por día.
En Oriveo, un límite de solicitudes aparece como «Límite de velocidad» en la web o «Límite de tasa del proveedor» en iPhone y Android. Si el mensaje menciona la cuota o el crédito, Oriveo muestra en su lugar «Cuota del proveedor agotada».
¿Qué significan los mensajes de error de Oriveo?
Estos son los mensajes que puedes ver en Oriveo, tal como aparecen en español:
| Lo que muestra Oriveo | Qué significa | Qué hacer |
|---|---|---|
| Guardado, pero la clave parece no válida. Puedes verificarla más tarde en los ajustes del proveedor. | Oriveo guardó el proveedor, pero el proveedor rechazó la clave durante la comprobación | Vuelve a copiar la clave y actualízala en los ajustes de ese proveedor |
| Clave API no válida (iPhone y Android) / API Key inválida (web) | El proveedor devolvió 401 o 403 | Revisa o reemplaza la clave; si es un 403, revisa la región y los permisos |
| Cuota del proveedor agotada | El proveedor dice que se agotó el crédito o la cuota de esta clave (402, o 429 que menciona la cuota) | Recarga saldo con el proveedor o cambia a otro modelo |
| Límite de velocidad (web) / Límite de tasa del proveedor (iPhone y Android) | Demasiadas solicitudes por ahora (429) | Espera un momento y vuelve a intentarlo |
| Cuota gratuita agotada (iPhone y web) / Cuota gratuita alcanzada (Android) | Se agotó la cuota diaria de Oriveo Free; no tiene nada que ver con tu propia clave | Agrega tu propia clave de API o espera al reinicio de las 00:00 UTC |

¿Usas un endpoint personalizado, un relay o un gateway?
Si te conectas a través de un endpoint personalizado, el error puede venir de ese servicio o del proveedor que hay detrás. Cuando Oriveo dice «Esta conexión no pudo comunicarse con su proveedor de origen.», es posible que la cuenta del propio servicio con el proveedor no sea válida, se haya quedado sin créditos o tenga un límite de solicitudes. No es un problema de tu configuración: cambia a otra conexión o contacta a quien administra el servicio.
Revisa esto antes de crear una clave nueva
Una clave nueva arregla un 401 y poco más. Repasa esta lista primero:
- Elegiste el proveedor correcto y, en Kimi, MiniMax, Qwen, SiliconFlow y Z.ai, la región correcta.
- Copiaste la clave completa, sin espacios.
- La cuenta tiene crédito o un método de facturación activo.
- Tu país o región está en la lista de países admitidos del proveedor.
- El modelo que elegiste está disponible para tu cuenta o tu nivel.
Preguntas frecuentes sobre la app
¿Por qué no funciona mi API key?
¿Qué significa el error 401 en una API key?
¿Qué es el error 402 Payment Required?
¿El error 429 es un límite de solicitudes o un problema de cuota?
¿Por qué mi API key de OpenAI dice insufficient_quota?
¿Por qué no funciona mi API key nueva si la copié bien?
Lecturas relacionadas
Del blog
Errores explicados con claridad para cada clave
Abre la app web o descarga Oriveo para iPhone o Android, agrega claves de 15 proveedores y entiende el motivo cuando una solicitud falla.
¿Todavía no tienes una clave de API? Con Oriveo Free puedes empezar sin ella.