> ## Documentation Index > Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt > Use this file to discover all available pages before exploring further. # Errores de la API de VU ONE FREE > Entienda las tres formas de error de la API de VU ONE FREE, los códigos de factor, el 402 de plan, el 429 y cuándo reintentar cada llamada. Esta página describe cómo leer una respuesta de error de la API de VU ONE FREE. Verá las tres formas de cuerpo de error, qué significa cada código y qué hacer en cada caso. Consulte esta página cuando una llamada falle. > [!WARNING] > > **VU ONE FREE es una versión limitada, en vista previa.** Solo la usan las cuentas de Identity Link que VU seleccionó hasta la disponibilidad general. Algunas funciones son del plan pago y las funciones, los límites y esta documentación pueden cambiar. [Vea qué incluye](https://docs.vu-one.com/vu-one/plan-free.md). ## Diagnóstico rápido | Si recibe | Causa más común | Vea | | - | - | - | | `401` | Falta el token o el token no es válido. | [Errores de permisos y contexto](#errores-de-permisos-y-contexto) | | `402` con código `4020` | La función es del plan pago. | [Error de plan: 402 y 404](#error-de-plan-402-y-404) | | `403` | Falta un permiso o un encabezado contradice el token. | [Errores de permisos y contexto](#errores-de-permisos-y-contexto) | | `404` sin cuerpo | La ruta no existe o la función está oculta en FREE. | [Error de plan: 402 y 404](#error-de-plan-402-y-404) | | `429` con código `505` | Se superó el límite de envíos de la cuenta. | La sección sobre el límite de envíos, más abajo | | `invalid_client`, `invalid_scope`, `invalid_grant` | La configuración del cliente OAuth o el flujo. | [Errores de OAuth](#errores-de-oauth) | ## Las tres formas de error La API devuelve el error en una de tres formas. La forma depende de la capa que responde. **Gateway.** El gateway responde antes de que la llamada llegue al servicio. Por ejemplo, cuando falta el token. ```json theme={null} { "error": "Unauthorized", "message": "Missing or invalid Authorization header", "timestamp": "" } ``` **API de negocio.** Los servicios de VU ONE responden con un código numérico, un mensaje y una clave de error. ```json theme={null} { "code": 400, "message": "", "codeKey": "SHARED.VALIDATION_ERROR" } ``` El campo `codeKey` tiene la forma `.`, por ejemplo `EMAIL.RATE_LIMIT`. Use `codeKey` para decidir qué hacer. El texto de `message` puede cambiar. **OAuth.** Los endpoints de token y de autorización siguen el estándar de OAuth 2.0. ```json theme={null} { "error": "invalid_scope", "error_description": "" } ``` ## Error de plan: 402 y 404 Algunas funciones son parte del plan pago. La API responde de dos formas. * **402.** La función es del plan pago. El cuerpo tiene el código `4020`. * **404 sin cuerpo.** La función está oculta en FREE, o la ruta no existe. ### Respuesta 402 ```json theme={null} { "code": 4020, "message": "This function is not included in the FREE plan.", "codeKey": "FEATURE_REQUIRES_PROMOTION", "feature": "feature.factors.smsOtp", "promotionUrl": "?utm_source=vuone&utm_medium=promotion_gate&utm_content=feature.factors.smsOtp" } ``` El campo `promotionUrl` aparece solo cuando el servicio que responde tiene configurada la URL de planes. El campo `feature` indica la función que pide el plan pago. > [!NOTE] > > Si el token no tiene el permiso, la API puede responder `403` antes de evaluar el plan. ### Respuesta 404 sin cuerpo Un `404` sin cuerpo puede significar tres cosas: * La ruta no existe. * La función está cerrada para FREE. * El flag de la función está apagado. La respuesta no le permite distinguir estos casos. Si espera una función incluida en FREE y recibe este `404`, revise la ruta y la documentación del factor. Si la función es del plan pago, use la sección de [Factores](https://docs.vu-one.com/vu-one/desarrolladores/factores.md) para saber qué factores están incluidos. ## Errores de factores Los errores de los factores usan el formato `.` en `codeKey`. Por ejemplo, `EMAIL.RATE_LIMIT` o `TOTP.VALIDATION_FAILED`. | Error | Código | HTTP | Qué significa | | - | - | - | - | | `NOT_FOUND` | 404 | 404 | El factor o el recurso no existe. | | `ALREADY_EXISTS` | 501 | 409 | El factor ya existe para esa cuenta. | | `BLOCKED` | 502 | 422 | El factor está bloqueado. | | `AUTO_LOCKED` | 503 | 422 | El factor se bloqueó por intentos fallidos. | | `NOT_ENABLED` | 504 | 422 | El factor no está habilitado. | | `RATE_LIMIT` | 505 | 429 | Se superó el límite de envíos. | | `EXPIRED` | 506 | 410 | El código o el factor venció. | | `SEND_FAILED` | 507 | 502 | No se pudo enviar el código. | | `POLICY_RESTRICTED` | 508 | 412 | La política no permite esta operación. | | `VALIDATION_FAILED` | 952 | 403 | El código o el dato enviado no es correcto. | | `ALREADY_USED` | 953 | 403 | El código ya se usó. | > [!NOTE] > > Los factores de contraseña usan códigos propios para algunos errores: `151` (ya existe), `152` (bloqueada, también por intentos fallidos), `154` (validación fallida), `155` (no habilitada) y `156` (vencida, con HTTP `422`). ## Errores comunes de la API Estos errores aparecen en cualquier endpoint de negocio. | Código | HTTP | `codeKey` | Qué significa | | - | - | - | - | | 400 | 400 | `SHARED.VALIDATION_ERROR` | El cuerpo no pasó la validación. | | 400 | 400 | `SHARED.MALFORMED_REQUEST` | El cuerpo no se pudo leer. | | 405 | 405 | `SHARED.METHOD_NOT_ALLOWED` | El método HTTP no está permitido para esa ruta. | | 157, 158, 159 o 400 | 422 | `PASSWORD.POLICY_VIOLATION` | La contraseña no cumple la política. `157`: vacía. `158`: muy corta. `159`: muy larga. | | 6000, 6001 u otro | 500 | `SHARED.INTERNAL_ERROR`, `SHARED.UNEXPECTED_ERROR` u otro | Error del servidor. Algunos servicios usan otro código. Use el estado HTTP `500`. | | 6102 | 503 | `SHARED.DEPENDENCY_ERROR` | Una dependencia no está disponible. | ## Errores de permisos y contexto Estos errores aparecen cuando el token o los encabezados no permiten la operación. | Respuesta | Causa | Qué hacer | | - | - | - | | `401`, `Missing or invalid Authorization header` | Falta el encabezado `Authorization` o no tiene el formato `Bearer`. | Envíe el token en el encabezado. | | `401`, `Invalid JWT token` | La firma, el formato o la vigencia del token no es válida. | Obtenga un token nuevo. | | `403`, `Tenant runtime access denied` | El tenant de la llamada no admite acceso en este momento. | Revise el host de la llamada y el estado del tenant. | | `403`, `GOVERNANCE.BUSINESS_SCOPE_ACCESS_DENIED` | Un encabezado `X-Business-Id`, `X-Channel-Id` o `X-Account-Scope` contradice el token. | Quite el encabezado o envíe el valor del token. | | `403`, `GOVERNANCE.TENANT_SCOPE_REQUIRED` | Un token de negocio intentó operar sobre otro negocio. | Use un token de alcance tenant, o opere sobre su propio negocio. | | `403` | El token no tiene el permiso `sys_<área>:` de la operación. | Pida al cliente el scope o el permiso que falta. | Consulte los encabezados de contexto en [Autenticación con OAuth 2.0 y OIDC](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md#encabezados-de-contexto). ## Errores de OAuth | Error | Cuándo aparece | Qué hacer | | - | - | - | | `invalid_client` | El ID o el secreto del cliente no son correctos, o el método de autenticación no coincide con el del cliente. | Revise las credenciales y el método de autenticación del cliente. | | `unauthorized_client` | El cliente no tiene habilitado el tipo de concesión que pidió. | Agregue el tipo de concesión al cliente, por ejemplo **Credenciales de Cliente**. | | `invalid_scope` | El cliente pidió un scope que no tiene registrado, o el cliente no tiene configuración de negocio. | Revise los scopes y la configuración de negocio del cliente. | | `invalid_grant` | El código de autorización, el `code_verifier` o el `refresh_token` no son válidos o vencieron. | Inicie el flujo de nuevo. | | `server_error` | Error del servidor de autorización. | Reintente con espera. Si persiste, revise el estado del tenant. | ## Límite de envíos: 429 En VU ONE FREE, los envíos de código por correo tienen un límite por cuenta. El límite predeterminado es de 5 envíos por hora en una ventana móvil. Cuando se supera el límite, la API responde: ```json theme={null} { "code": 505, "message": "", "codeKey": "EMAIL.RATE_LIMIT" } ``` Espere antes de enviar otro código a la misma cuenta. El límite usa una ventana móvil de una hora. Cada envío deja de contar cuando sale de esa ventana. ## Cómo reintentar Reintente solo los errores que pueden cambiar con el tiempo. Un error de datos no se corrige reintentando. | Código | ¿Reintentar? | Cómo | | - | - | - | | 400 | No | Corrija el cuerpo de la solicitud. | | 401 | Una vez | Obtenga un token nuevo y reintente. | | 402 | No | La función es del plan pago. | | 403 | No | Revise el permiso o el encabezado de contexto. | | 404 | No | Revise la ruta y el plan. | | 409 | No | Consulte el recurso existente. | | 422 | No | Corrija el valor que no cumple la política. | | 429 | Sí | Espere la ventana del límite antes de reintentar. | | 500 | Solo una vez | Espere unos segundos. Si persiste, contacte a VU. | | 502 y 503 | Sí | Reintente con espera creciente entre intentos. | > [!WARNING] > > Antes de reintentar un `POST` que crea un recurso, consulte si el recurso ya existe. Un reintento puede crear un duplicado. Por ejemplo, antes de crear una cuenta, busque la identidad con `GET /api/v1/identities`. > [!TIP] > > Registre el `code`, el `codeKey` y el encabezado `X-Business-Id` de cada error. Esos datos ayudan al equipo de VU a encontrar la llamada en sus registros. ## Qué sigue > [card] [Autenticación con OAuth 2.0 y OIDC](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md) > > Revise los tokens, los scopes y los encabezados de contexto. > [card] [Factores de autenticación en la API](https://docs.vu-one.com/vu-one/desarrolladores/factores.md) > > Revise los factores incluidos en FREE y sus límites. > [card] [Cuentas, identidades y contraseñas](https://docs.vu-one.com/vu-one/desarrolladores/cuentas.md) > > Revise las operaciones de cuentas y contraseñas. > [card] [FREE y plan pago](https://docs.vu-one.com/vu-one/plan-free.md) > > Revise qué funciones incluye VU ONE FREE y cuáles responden `402`. ## Related topics - [Factores de autenticación en la API](https://docs.vu-one.com/vu-one/desarrolladores/factores.md) - [Aprovisionamiento con SCIM 2.0](https://docs.vu-one.com/vu-one/desarrolladores/scim.md) - [Cuentas, identidades y contraseñas](https://docs.vu-one.com/vu-one/desarrolladores/cuentas.md) - [Autenticación con OAuth 2.0 y OIDC](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md) - [Guía para desarrolladores de VU ONE FREE](https://docs.vu-one.com/vu-one/desarrolladores/introduccion.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.