Errores de API key

¿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.

Actualizado
  • 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.
Oriveo en iPhone: la pantalla de proveedores, con los proveedores que has conectado y el gasto de este mes.

¿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.

Guía rápida: 401, 402, 403, 429 y 5xx
CódigoQué suele significar¿Se arregla esperando?Qué hacer
401La clave es incorrecta: falta un carácter, sobra un espacio, la clave fue borrada o es de otro proveedor o regiónNoVuelve a copiar la clave o crea una nueva; revisa el proveedor y la región
402Hace falta pagar: se acabó tu saldo prepagado o tus créditos, o hay un problema de facturaciónNoRecarga saldo o corrige el método de pago en la página de facturación del proveedor
403La clave funciona, pero no tiene permiso: país o región no admitidos, sin acceso a ese modelo o falta una verificaciónNoRevisa las regiones admitidas, los permisos de la clave y cualquier verificación pendiente
404El nombre del modelo o la dirección son incorrectosNoElige otro modelo o revisa la dirección
429Demasiadas solicitudes en poco tiempo o, con algunos proveedores, saldo agotado o un límite de gastoMuchas veces, si es un límite de solicitudesEspera y reintenta; si el mensaje menciona quota, balance, credit o spend limit, recarga saldo o sube el límite
500–504, 529Una falla o una sobrecarga del lado del proveedorNormalmente 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.

¿Por qué dice saldo insuficiente o cuota agotada?
ProveedorCódigo cuando se acaba el saldoQué dice el mensajePágina oficial
OpenAI429credit_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_errorplatform.claude.com/docs/en/api/errors (códigos); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (mensaje)
Google Gemini402 (facturación prepagada)payment_required; un 403 también puede indicar un saldo impago en Cloud Billingaistudio.google.com/docs/api-errors
OpenRouter402«Your account or API key has insufficient credits» (créditos insuficientes en la cuenta o la clave)openrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balanceapi-docs.deepseek.com/quick_start/error_codes
xAI (Grok)No se indicaLas solicitudes se rechazan cuando se acaban los créditos prepagadosdocs.x.ai/console/billing
Mistral AI402Payment requireddocs.mistral.ai/resources/error-glossary
GroqNo documentadoGroq cobra después del uso; su página de errores no incluye ningún error de saldoconsole.groq.com/docs/errors
Together AI402Payment Requireddocs.together.ai/docs/error-codes
Fireworks AI402Payment Requireddocs.fireworks.ai/guides/inference-error-codes
MiniMaxNo se indica (código de negocio 1008)insufficient balanceplatform.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)403Arrearage o isv.OUT_OF_SERVICE (cuenta con deuda pendiente)alibabacloud.com/help/en/model-studio/error-code
Kimi (Moonshot AI)429exceeded_current_quota_errorplatform.kimi.ai/docs/api/errors
SiliconFlowNo documentadoNo figura ningún error de saldodocs.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:

¿Qué significan los mensajes de error de Oriveo?
Lo que muestra OriveoQué significaQué 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ónVuelve 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 403Revisa o reemplaza la clave; si es un 403, revisa la región y los permisos
Cuota del proveedor agotadaEl 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 claveAgrega tu propia clave de API o espera al reinicio de las 00:00 UTC
Pantalla «Proveedores» de Oriveo con proveedores conectados como OpenAI, Z.ai, Groq, Gemini y Anthropic, cada uno con su gasto
Abre un proveedor de esta lista para revisar o reemplazar su clave.

¿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?
Mira el número del error. 401 significa que la clave es incorrecta; 402, que te quedaste sin saldo o sin créditos; 403, que la solicitud no está permitida (a menudo por región o permisos); y 429, demasiadas solicitudes o, con algunos proveedores, saldo agotado.
¿Qué significa el error 401 en una API key?
Que el proveedor no reconoce la clave. Vuelve a copiarla sin espacios, comprueba que sea del proveedor y la región que elegiste, o crea una clave nueva.
¿Qué es el error 402 Payment Required?
Que te quedaste sin saldo prepagado o sin créditos, o que hay un problema de pago. Lo usan DeepSeek, OpenRouter, Mistral, Together, Fireworks y la facturación prepagada de Gemini. Recarga en la página de facturación del proveedor; esperar no lo arregla.
¿El error 429 es un límite de solicitudes o un problema de cuota?
Puede ser cualquiera de los dos. Normalmente es un límite de solicitudes que se resuelve tras una espera corta. Pero OpenAI, Kimi y Z.ai también devuelven 429 cuando tu saldo está vacío, así que si el mensaje menciona quota, balance o credit, agrega crédito en lugar de esperar.
¿Por qué mi API key de OpenAI dice insufficient_quota?
Porque a tu cuenta de API de OpenAI no le queda crédito prepagado. OpenAI devuelve 429 con el código credit_balance_exhausted, y el tipo de error puede seguir diciendo insufficient_quota. Agrega crédito en la configuración de facturación de OpenAI; una clave nueva no sirve.
¿Por qué no funciona mi API key nueva si la copié bien?
Normalmente porque la cuenta todavía no tiene crédito o la facturación no está configurada, porque la clave es de otra región o porque la API no está disponible en tu país. Revisa eso antes de crear otra clave.

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.