Errores y límites

El error llega en el formato de la API que invocaste: el objeto error para OpenAI, {"type": "error", "error": {...}} para Anthropic y error con los campos status y details para Gemini. Por eso, los SDK los reconocen como errores normales de API.

• error.code y error.reason indican la misma clase de error de la tabla siguiente. error.type es el valor estándar del formato (por ejemplo, invalid_request_error o server_error).
• error.request_id (en Anthropic, request_id en el nivel superior), el encabezado X-Request-ID y el final del mensaje contienen el identificador de solicitud.
• En Gemini, la clase se encuentra en error.details: ErrorInfo.reason : el mismo código en mayúsculas (por ejemplo, MODEL_OVERLOADED), domain — ailoot.ai; el identificador de solicitud está en RequestInfo.requestId.
• En Gemini, los errores 5xx que no se deben reintentar automáticamente y result_pending_check se devuelven con el código de estado 409 y status ABORTED, para que los SDK y CLI de Gemini no los reintenten automáticamente. La clase de error está en ErrorInfo.reason (por ejemplo, MODEL_TIMEOUT o RESULT_PENDING_CHECK).
• La respuesta en formato OpenAI también incluye los campos de nivel superior code y message para los clientes antiguos.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "reason": "invalid_api_key",
    "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e."
  },
  "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e"
}

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ailoot.ai",
        "metadata": {
          "code": "invalid_api_key",
          "reason": "invalid_api_key",
          "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b"
      }
    ]
  }
}

Los códigos de respuesta del modelo y verificación del resultado (502, 503 y 504) ahora hacen referencia al modelo o a la solicitud: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed y result_pending_check. Si tu código compara error.code con los valores antiguos, reemplázalos por los de la tabla; para saber la equivalencia entre los códigos antiguos y los nuevos, consulta con soporte.

• Verifica primero X-Should-Retry: si ves false, result_pending_check o model_timeout , no reintentes automáticamente. Busca el Request ID en el historial del panel para consultar el resultado y el cargo.
• Es seguro reintentar cuando recibes X-Should-Retry: true: espera Retry-After segundos. En los errores 5xx, el código por sí solo no basta: el resultado podría haberse generado ya. Consulta primero el historial del panel o contacta a soporte e indica el Request ID. Es especialmente importante para imágenes, videos, música y pasos de agentes que tardan mucho.
• Reintentar no solucionará el problema: 400, 401, 402, 403 y 404; corrige primero la solicitud, la clave o el saldo.

La frecuencia y el número de solicitudes simultáneas se limitan para tu cuenta en su conjunto, no para cada clave. Si se supera el límite, recibirás 429 rate_limit_exceeded con el encabezado Retry-After: 10. Si el propio modelo está sobrecargado, recibirás 503 model_overloaded con Retry-After: 30. Si necesitas más capacidad, contacta a soporte.

Los límites de gasto se configuran en la clave: el límite total devuelve 402 api_key_quota_exhausted y las ventanas de 5 horas, 1 día y 7 días devuelven 429 usage_limit_reached. Más información en Claves y dirección de la API.

Puedes consultar la lista de modelos con saldo cero; para generar necesitas saldo para la reserva. Los modelos NVIDIA, como Nemotron, funcionan mediante una cola compartida: con una carga alta, la respuesta puede tardar más o se puede devolver un error de «modelo temporalmente sobrecargado» con la cabecera Retry-After. Reintenta tras el tiempo indicado. Los precios están en el catálogo y los cargos se calculan igual que en los demás modelos.

El modelo define los límites de tamaño: contexto, es decir, cuántos tokens puedes enviar, y longitud máxima de respuesta. Se indican en el catálogo.