> ## Documentation Index > Fetch the complete documentation index at: https://docs.flexinference.com/llms.txt > Use this file to discover all available pages before exploring further. # Errores > Los formatos de error por superficie, los códigos de FlexInference y cómo se normalizan los errores del proveedor. Los errores utilizan el formato del endpoint al que se llama. `/v1/responses` y `/v1/chat/completions` devuelven errores con formato OpenAI. `/v1/messages` devuelve errores con formato Anthropic. `/v1/interactions` devuelve errores con formato Google. Los errores de FlexInference y los errores de los proveedores upstream siguen la misma regla, por lo que cada endpoint tiene un único formato de error. ¿Ve errores 5xx o tiempos de espera? Consulte primero [status.flexinference.com](https://status.flexinference.com). Muestra el tiempo de actividad en vivo de la API, el sitio web, la documentación y el servidor MCP, además de cualquier incidente abierto. En `/v1/responses` y `/v1/chat/completions`, los errores utilizan el formato OpenAI: ```json theme={null} { "error": { "message": "The API key on this request was rejected - either it does not match FlexInference's key format (`flex_live_` followed by 24 hex characters and a 6-hex checksum), or it is well-formed but does not match any key on record. Copy the exact, current key from the FlexInference dashboard under Settings -> API keys, then send it as `Authorization: Bearer `.", "type": "authentication_error", "code": "invalid_api_key", "param": null, "doc_url": "https://docs.flexinference.com/errors#invalid_api_key" } } ``` El mismo error en `/v1/messages` utiliza el formato de Anthropic. En `/v1/interactions`, utiliza el formato de Google: ```json theme={null} { "type": "error", "error": { "type": "authentication_error", "message": "..." } } ``` ```json theme={null} { "error": { "code": 401, "message": "...", "status": "UNAUTHENTICATED" } } ``` El estado HTTP y el mensaje permanecen iguales en todas las superficies; solo cambia el envoltorio. El formato OpenAI contiene todos los detalles. `type` utiliza las categorías de OpenAI (`invalid_request_error`, `authentication_error`, `rate_limit_error`), además de `flexinference_error` para fallos internos y `billing_error` cuando el estado de facturación pausa las solicitudes facturables. `code` es la razón legible por máquina. `param` nombra el campo ofensivo cuando aplica. `doc_url` enlaza a la fila de ese código a continuación, o es `null` cuando se desconoce. El formato de Anthropic lleva un `type` de Anthropic mapeado desde el estado más el mensaje. El formato de Google lleva el `code` numérico, el mensaje y un `status` canónico. Los campos `code` y `doc_url` específicos de FlexInference solo aparecen en el formato OpenAI. ## Códigos de FlexInference Estos códigos provienen de FlexInference. Ramifique en `error.code`; `error.message` está escrito para desarrolladores e incluye la solución si existe. Varios errores involucran a `start_within`. Para los valores de duración en modelos compatibles con flex, FlexInference intenta primero el nivel flex más económico. Si flex no puede iniciarse dentro de esa ventana, FlexInference envía la misma solicitud al nivel estándar. El estándar es la ruta de respaldo, no el primer intento. | Status | Code | Meaning | | ------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `401` | `missing_api_key` | No hay encabezado `Authorization`, o el valor no es `Bearer `. Envíe `Authorization: Bearer `. | | `401` | `invalid_api_key` | La clave no coincide con el formato de FlexInference (`flex_live_` + 24 caracteres hexadecimales + un checksum de 6 hexadecimales), o coincide con el formato pero es desconocida porque fue revocada, regenerada o mal escrita. Copie la clave actual desde el panel de control. | | `429` | `rate_limit_exceeded` | La solicitud alcanzó uno de estos límites: intentos de autenticación fallidos desde su IP de cliente, solicitudes desde una clave o IP de cliente, solicitudes desde su organización o arrendamientos de concurrencia flex facturables. El limitador de concurrencia flex facturable por defecto es de 20 solicitudes en curso. Espere los segundos indicados en `Retry-After`, generalmente 60s para el limitador de inundación de autenticación y 5s para los otros limitadores de solicitudes. | | `402` | `payment_required` | Esta organización tiene un saldo vencido o no tiene un método de pago registrado, por lo que las solicitudes flex facturables están en pausa. El enrutamiento gratuito (`default`, `priority`, `auto`) y todas las solicitudes de nivel Anthropic siguen funcionando. Agregue o actualice una tarjeta en la página [Billing](/es/billing) del panel de control, luego reintente. Este es el único código con `type: billing_error`. | | `413` | `request_too_large` | El cuerpo de la solicitud excede el límite de 1,000,000 bytes de FlexInference, verificado tanto contra el `Content-Length` declarado como contra los bytes realmente transmitidos. Los archivos base64 en línea grandes son la causa habitual. Reduzca el tamaño de la carga útil o apunte a una URL alojada en su lugar. | | `400` | `no_byok_key` | No hay una clave OpenAI configurada para su organización. Agregue una en el panel de control en Settings -> API keys. Las claves BYOK se almacenan cifradas; si existe una clave almacenada pero no se puede descifrar, la solicitud falla como `500 internal_error`, no con este código. Cada ruta que nombre en una cadena `provider` necesita su clave: una clave faltante es un error de configuración, no un fallo transitorio, por lo que se rechaza antes de cualquier llamada upstream y nunca pasa a la siguiente ruta. | | `400` | `no_gemini_key` | Igual que `no_byok_key`, para un modelo `gemini-*`: no hay una clave Gemini configurada para su organización. Agregue una en el panel de control. | | `400` | `no_anthropic_key` | Igual que `no_byok_key`, para un modelo `claude-*`: no hay una clave Anthropic configurada para su organización. Agregue una en el panel de control. | | `400` | `no_bedrock_key` | Igual que `no_byok_key`, para una ruta `bedrock` en la cadena `provider`: no hay una clave Bedrock configurada para su organización. Bedrock sirve modelos `claude-*` a través de Amazon Bedrock usando su propia clave; agregue una en el panel de control en Settings -> API keys. Una entrada `bedrock` en cualquier parte de la cadena requiere la clave, por lo que una clave faltante se rechaza antes de cualquier llamada upstream. | | `400` | `no_vertex_key` | Igual que `no_byok_key`, para una ruta `vertex` en la cadena `provider`: no hay una clave Vertex configurada para su organización. Vertex sirve modelos `gemini-*` a través de Google Vertex AI usando su propia clave express (prefijo `AQ.`). Agregue una en el panel de control en Settings -> API keys. Una entrada `vertex` en cualquier parte de la cadena requiere la clave, por lo que una clave faltante se rechaza antes de cualquier llamada upstream. | | `400` | `missing_model` | El campo `model` falta, está vacío o no es una cadena. Agregue una cadena no vacía, por ejemplo `"model": "gpt-5.5"`. | | `400` | `missing_start_within` | El campo `start_within` requerido falta y no se aplica ningún valor predeterminado. `start_within` establece cuánto tiempo está dispuesto a esperar para que la solicitud comience. Use `default`, `priority`, `auto` o una duración como `HHh-MMm-SSs`, por ejemplo `00h-00m-30s` para esperar hasta treinta segundos. | | `400` | `invalid_start_within` | `start_within` no es una cadena, no coincide con una de las cuatro formas aceptadas, o se resuelve fuera de la ventana permitida de 5 a 600 segundos (10 minutos) para una duración. Coincida con la forma exacta y mantenga las duraciones dentro de 5s-600s. Por ejemplo, use `"start_within": "00h-00m-30s"` para una ventana de treinta segundos, o `"start_within": "default"` para omitir la carrera flex. | | `400` | `auto_unsupported_for_gemini` | Se usó `start_within: "auto"` en un modelo Gemini. Los niveles de Gemini son solo `flex`, `standard` y `priority`; no hay `auto` para resolver. Use `default`, `priority` o una duración en su lugar. | | `400` | `flex_unsupported_for_anthropic` | Se envió una duración `start_within` (carrera flex) a un modelo `claude-*`, pero Anthropic no tiene un nivel flex contra el cual competir. FlexInference ya no sirve silenciosamente el estándar para una carrera flex inaplicable. Use un nivel `start_within` (`default`, `priority`, `auto`) u omítalo. | | `400` | `flex_model_not_capable` | Se envió una duración `start_within` a un modelo OpenAI o Gemini que no está en la lista de permitidos de flex. Use un nivel `start_within` o elija un modelo compatible con flex. | | `400` | `service_tier_not_allowed` | La solicitud incluyó `service_tier`. FlexInference deriva el nivel de `start_within`; aceptar `service_tier` proporcionado por el llamador requeriría sobrescribirlo, por lo que el enrutador rechaza el campo. Elimine `service_tier` y exprese la misma intención a través de `start_within`. También aplica en `/v1/interactions` y `/v1/messages`. | | `400` | `unsupported_parameter` | Se envió un parámetro nativo del proveedor a un proveedor diferente, o un campo canónico de Responses no tiene un mapeo para el proveedor de destino. Los parámetros nativos de Chat pasan en los modelos OpenAI pero fallan en los modelos Gemini o Claude. Los parámetros nativos de Anthropic pasan en los modelos Claude pero fallan en los modelos OpenAI o Gemini, excepto los bloques de contenido `document` y `file` con fuentes base64, que se traducen a todos los proveedores. `cache_control`, citas y otros parámetros nativos del proveedor aún fallan entre proveedores. Elimine el campo nombrado o elija un modelo cuyo proveedor lo posea; `error.param` nombra exactamente cuál. Consulte [SDKs](/es/sdks). | | `400` | `unsupported_generation_config` | En `/v1/interactions`, se estableció un campo `generation_config.*` no mapeado mientras se apuntaba a un modelo que no era Gemini. Las claves extra nativas de Gemini pasan en los modelos Gemini. Elimine el campo nombrado o apunte a un modelo Gemini. | | `400` | `unsupported_tool` | El array `tools` contiene una herramienta incorporada que hace que el modelo emita una salida no textual, actualmente `image_generation`. FlexInference solo sirve salida textual, en cada endpoint. Elimine esa entrada de herramienta; las herramientas de función y `web_search` siguen siendo compatibles. | | `400` | `unsupported_value` | El campo `n` de Chat Completions se estableció en algo diferente de `1`. La API de Responses subyacente siempre produce una única generación, por lo que `n` debe ser `1` u omitirse. Por ejemplo, envíe `"n": 1` o omita `n`. | | `400` | `invalid_json` | El cuerpo no es JSON sintácticamente válido (`JSON.parse` falló). Corrija la sintaxis; una coma al final o una clave sin comillas son causas comunes. | | `400` | `invalid_body` | El cuerpo se analizó como JSON, pero el valor de nivel superior no es un objeto JSON. Los arrays, cadenas, números, booleanos y nulos son inválidos. Envuelva sus campos en un único objeto `{...}`. | | `400` | `invalid_stream` | El campo `stream` debe ser un booleano JSON. FlexInference no convertirá un valor no booleano, incluida la cadena `"true"`, porque eso podría elegir el modo de respuesta incorrecto. Envíe `stream` como un booleano real, por ejemplo `"stream": true`, u omítalo para una respuesta no transmitida. | | `400` | `invalid_retry` | El valor `retry` no es válido. `retry` es un objeto `{ count, backoff?, jitter? }` donde `count` es un entero de 1 a 5 (cuántas veces FlexInference vuelve a intentar el nivel upstream en un 429 o 5xx transitorio), `backoff` es `"exponential"` o `"linear"`, y `jitter` es un booleano. Este código cubre un `count` faltante o fuera de rango, un valor `backoff` incorrecto, un `jitter` no booleano y cualquier subclave desconocida. Corrija o elimine el campo, por ejemplo `"retry": {"count": 2}`. `retry` solo vuelve a intentar el nivel establecido antes de que la respuesta se confirme; nunca reintenta después del primer byte, un fallo de autenticación o un 4xx del cliente. | | `400` | `invalid_provider_chain` | El array `provider` opcional está mal formado: no es un array, está vacío, tiene un nombre de ruta desconocido, está duplicado o tiene más de tres entradas. Cada entrada debe ser una de `google`, `openai`, `anthropic`, `vertex` o `bedrock`; el elemento 0 es la ruta principal y el resto son la cadena de respaldo ordenada del mismo modelo. Omita `provider` para usar la ruta nativa del modelo, o corrija el array, por ejemplo `["google", "vertex"]`. Un código cubre todas las razones de una cadena mal formada, como `invalid_retry`; `error.message` nombra el fallo específico. | | `400` | `provider_model_mismatch` | Una ruta en la cadena `provider` no puede servir el modelo solicitado. Cada ruta sirve una familia de modelos: `openai` sirve modelos GPT y de la serie o, `google` y `vertex` sirven Gemini, y `anthropic` y `bedrock` sirven Claude. Elimine la ruta que no coincide con este modelo, o envíe la solicitud a un modelo que esa ruta pueda servir, por ejemplo `["anthropic"]` para un modelo `claude-*`. | | `400` | `flex_unsupported_on_cloud` | Se envió una duración `start_within` (una carrera flex) con una ruta de nube (`vertex` o `bedrock`) como elemento 0, pero las rutas de nube no tienen un nivel flex contra el cual competir. FlexInference no sirve silenciosamente el nivel predeterminado para una carrera flex inaplicable. Use un nivel `start_within` (`default`, `priority` o `auto`) para ejecutar la ruta de nube como una llamada estándar simple, o coloque una ruta directa compatible con flex (`openai` o `google`) primero en `provider`. | | `400` | `bedrock_model_unavailable` | Una ruta `bedrock` no tiene un ID de modelo de Amazon Bedrock para este slug, por lo que la solicitud se rechaza antes de cualquier llamada upstream. Hoy eso significa `claude-opus-4-1` (eliminado de la ruta `bedrock` porque AWS lo publica solo en EE. UU.; envíelo a `anthropic` en su lugar) o texto `claude-*` arbitrario no mapeado. Bedrock sirve cada modelo Claude mapeado a través de su perfil de inferencia `global.`, por lo que un modelo servido es accesible desde cualquier región; la geolocalización derivada de la región (`us-*` -> `us.`, `eu-*` -> `eu.`, todo lo demás -> `global.`) es solo un respaldo inactivo para un futuro modelo que no publique un perfil `global.`. Esto es permanente para ese slug, no transitorio. Cada ruta nombrada en `provider` debe poder servir la solicitud, por lo que nombrar `bedrock` falla la solicitud incluso cuando otra ruta en la cadena podría servir este modelo. Elimine `bedrock` de `provider`, o envíe el modelo a una ruta que lo sirva. | | `403` | `bedrock_model_access_denied` | Amazon Bedrock rechazó el modelo para la cuenta de AWS detrás de la clave Bedrock de su organización, y FlexInference pasa la propia explicación de Bedrock (`... no está disponible para esta cuenta`). Su clave Bedrock es válida y funciona: esto es una falta de concesión de acceso por modelo en la cuenta de AWS, no un problema de clave, por lo que reemplazar la clave no lo solucionará. Para la mayoría de los modelos Claude, conceda el modelo en la consola de Amazon Bedrock en Model access. Los cuatro modelos más nuevos (`claude-sonnet-5`, `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`) necesitan además una configuración de cuenta única que la concesión de la consola no cubre: una opción de retención de datos `provider_data_share` y un acuerdo de modelo, ejecutado con credenciales de administrador de AWS; consulte [la configuración de los modelos más nuevos](/es/models). De lo contrario, envíe el modelo a la ruta `anthropic` en su lugar, o elija un modelo que la cuenta ya tenga. Esto es una brecha de configuración permanente, por lo que es un `403` y no un `502` reintentable. | | `404` | `unknown_url` | Ruta incorrecta. Use `/v1/responses`, `/v1/chat/completions`, `/v1/interactions` o `/v1/messages`. | | `405` | `method_not_allowed` | La ruta existe, pero los endpoints de FlexInference solo aceptan `POST`. Envíe un `POST` con un cuerpo JSON. | | `499` | `client_closed_request` | El cliente se desconectó antes de que FlexInference terminara de responder, generalmente debido a una pestaña cerrada, una solicitud cancelada o un tiempo de espera del lado del cliente. Esto no se cuenta como un fallo del servicio. Si no tenía intención de cancelar, aumente el tiempo de espera de su cliente y deje que la solicitud finalice. Una solicitud flex puede tardar legítimamente hasta 10 minutos. | | `500` | `internal_error` | FlexInference falló fuera de la validación de entrada. Reintente una vez; si persiste, contacte a soporte con la marca de tiempo aproximada y su organización. | | `500` | `server_misconfigured` | Una vinculación o secreto requerido está ausente o mal formado, por lo que FlexInference no puede autenticar a los llamadores o descifrar las claves BYOK. Esto es un fallo de despliegue del lado del servidor distinto de `internal_error`, no un problema con su solicitud. Reintente en breve y contacte a soporte si persiste. | | `502` | `upstream_stream_failed` | El proveedor upstream confirmó una respuesta, luego su stream terminó sin un evento de finalización o falló a mitad del stream sin un error del proveedor que pasar. Esto es un fallo transitorio de upstream o de red entre FlexInference y el proveedor, no de su solicitud. Reintente una vez. Si persiste para un modelo, el proveedor o el modelo pueden estar degradados; intente con otro modelo, o establezca una ventana `start_within` más corta para que un intento lento escale a su nivel estándar antes. Distinto de un `5xx` upstream que el propio proveedor devolvió, que se reformatea a su superficie con el mensaje del proveedor. | | `502` | `upstream_unavailable` | FlexInference no pudo abrir una conexión con el proveedor upstream antes de que se confirmara cualquier respuesta (la conexión fue rechazada, o falló DNS, TLS o la red). Esto es un fallo de upstream o de red, no de su solicitud. Reintente una vez; si sigue fallando para un modelo, el proveedor puede estar caído, así que intente con otro modelo. Distinto de `upstream_stream_failed`, donde una respuesta ya había comenzado. | | `502` | `upstream_auth_failed` | El proveedor upstream rechazó la clave API que su organización adjuntó para él (HTTP 401 o 403, antes de que se confirmara cualquier respuesta). Esto no es un fallo de su clave FlexInference; la credencial del proveedor almacenada carece de acceso, fue revocada, expiró o es inválida por alguna otra razón. Pida a un administrador de la organización que actualice la clave del proveedor adjunta en el panel de control en Settings -> API keys, luego reintente. | | `502` | `all_routes_failed` | Todas las rutas en la cadena `provider` fallaron transitoriamente antes de que se confirmara cualquier respuesta (cada intento upstream devolvió un `429`, un `5xx`, un error de conexión o un tiempo de espera), por lo que no quedó ninguna ruta a la que recurrir. Esta es una condición de upstream o de red, no su solicitud, por lo que se informa como `502` aunque la cadena misma esté agotada. Reintente una vez; los breves fallos de upstream suelen resolverse. Si persiste, intente con un modelo diferente o reduzca la cadena a las rutas que estén actualmente saludables. | | `503` | `usage_persistence_unavailable` | FlexInference no pudo registrar de forma duradera el uso de una solicitud facturable. Reintente una vez que la persistencia de uso se recupere. | | `504` | `upstream_timeout` | El proveedor upstream no comenzó a responder antes del tiempo de espera de upstream de FlexInference, por lo que la solicitud fue abortada entre FlexInference y el proveedor. Esto es casi siempre una ralentización o interrupción transitoria del proveedor, no su solicitud, y se informa como `504` en lugar de un error interno. Reintente una vez; si sigue agotando el tiempo de espera para un modelo, el proveedor puede estar degradado, así que intente con otro modelo, o para una duración `start_within` establezca un plazo más corto como `00h-00m-30s`. | El array `provider` fija su ruta. `google`, `openai` y `anthropic` son rutas directas; `vertex` y `bedrock` son rutas en la nube que sirven `gemini-*` y `claude-*` en Google Vertex AI y Amazon Bedrock respectivamente. Una ruta en la nube cuya clave no está configurada devuelve [`no_vertex_key`](/es/errors#no_vertex_key) o [`no_bedrock_key`](/es/errors#no_bedrock_key), el mismo patrón de clave faltante que [`no_gemini_key`](/es/errors#no_gemini_key) y [`no_anthropic_key`](/es/errors#no_anthropic_key) anteriores. `upstream_auth_failed` cubre cualquier credencial de proveedor adjunta que el upstream rechace, incluidas las rutas en la nube. Consulte [provider routing](/es/models). ## Encabezados de resultado de Flex Las respuestas `200` exitosas incluyen encabezados de resultado de Flex en cada endpoint, tanto para llamadas de streaming como no streaming. Las respuestas de error utilizan el cuerpo del error en su lugar. | Header | Meaning | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-flexinference-flex-requested` | `true` cuando el llamador envió una duración `start_within`; `false` cuando el llamador envió `default`, `priority` o `auto`. | | `x-flexinference-flex-applied` | `true` solo cuando el nivel flex sirvió la respuesta. | | `x-flexinference-flex-reason` | Resultado flex legible por máquina. Consulte los valores a continuación. | | `x-flexinference-provider-surface` | Superficie de ejecución del proveedor. Los valores son `openai.responses`, `openai.chat`, `gemini.interactions` y `anthropic.messages`. Esto no siempre es el endpoint del llamador. Una llamada a `/v1/chat/completions` con un modelo OpenAI reporta `openai.responses` a menos que se requiera el passthrough nativo de Chat, en cuyo caso reporta `openai.chat`. | Valores de `x-flexinference-flex-reason` en vivo: | Reason | Meaning | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `not_requested` | La solicitud usó `default`, `priority` o `auto`, por lo que no se solicitó ninguna carrera flex. | | `flex_committed` | La carrera flex se comprometió. La respuesta muestra `service_tier: "flex"` y `x-flexinference-flex-applied: true`. | | `flex_lost_race` | La solicitud usó una duración en un modelo compatible con flex, pero flex no comenzó dentro de la ventana y la solicitud recurrió al estándar. | Una duración que no puede ejecutar una carrera flex devuelve `400` (`flex_unsupported_for_anthropic` en un modelo `claude-*`, `flex_model_not_capable` en un modelo OpenAI/Gemini no compatible con flex); las razones del encabezado describen solo las solicitudes que ejecutaron flex o no lo solicitaron. ## Errores del proveedor Los errores del proveedor upstream utilizan el mismo formato de superficie que los errores de FlexInference. FlexInference mantiene el estado y el mensaje del proveedor, luego los emite en el formato del endpoint al que llamó. Un `400` del proveedor por un parámetro incorrecto, un `401` por una clave de proveedor inválida o un límite de `rate_limit` `429` en el intento estándar, regresan con ese formato. No recibe el cuerpo sin procesar del proveedor. Por ejemplo, si llama a `/v1/messages` y un error de un modelo OpenAI regresa con formato Anthropic. Los campos `code` y `doc_url` específicos de FlexInference solo aparecen en el formato OpenAI; los errores del proveedor llevan el mensaje del proveedor con el `type` o `status` de la superficie. En la superficie de OpenAI, ramifique en `error.code` para un manejo específico de FlexInference, como solicitar al usuario que agregue una clave BYOK en `no_byok_key`. Trate los códigos desconocidos como errores ordinarios de OpenAI. ## Manejo de errores en el código Los SDK de OpenAI lanzan excepciones en respuestas que no son 2xx y adjuntan el cuerpo analizado. ```python Python theme={null} from openai import APIStatusError try: resp = client.responses.create( model="gpt-5.5", input="hi", extra_body={"start_within": "00h-00m-30s"}, ) except APIStatusError as e: code = (e.body or {}).get("error", {}).get("code") if code == "no_byok_key": print("Add your OpenAI key in the dashboard.") else: raise ``` ```typescript Node theme={null} import OpenAI from "openai"; try { await client.responses.create({ model: "gpt-5.5", input: "hi", start_within: "00h-00m-30s", } as any); } catch (e) { if (e instanceof OpenAI.APIError && e.code === "no_byok_key") { console.log("Add your OpenAI key in the dashboard."); } else { throw e; } } ```