Errores de la API de VU ONE FREE

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.

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.

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
`402` con código `4020`	La función es del plan pago.	Error de plan: 402 y 404
`403`	Falta un permiso o un encabezado contradice el token.	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
`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

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.

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header",
  "timestamp": "<fecha-ISO-8601>"
}

API de negocio. Los servicios de VU ONE responden con un código numérico, un mensaje y una clave de error.

{
  "code": 400,
  "message": "<texto-del-error>",
  "codeKey": "SHARED.VALIDATION_ERROR"
}

El campo codeKey tiene la forma <DOMINIO>.<ERROR>, 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.

{
  "error": "invalid_scope",
  "error_description": "<texto-del-error>"
}

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

{
  "code": 4020,
  "message": "This function is not included in the FREE plan.",
  "codeKey": "FEATURE_REQUIRES_PROMOTION",
  "feature": "feature.factors.smsOtp",
  "promotionUrl": "<url-de-planes>?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.

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 para saber qué factores están incluidos.

Errores de factores

Los errores de los factores usan el formato <TIPO>.<ERROR> 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ó.

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>:<acción>` 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.

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:

{
  "code": 505,
  "message": "<texto-del-error>",
  "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.

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.

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

Autenticación con OAuth 2.0 y OIDC

Revise los tokens, los scopes y los encabezados de contexto.

Factores de autenticación en la API

Revise los factores incluidos en FREE y sus límites.

Cuentas, identidades y contraseñas

Revise las operaciones de cuentas y contraseñas.

FREE y plan pago

Revise qué funciones incluye VU ONE FREE y cuáles responden 402.

Empezar aquí

Administración

Desarrolladores

Errores de la API de VU ONE FREE

Diagnóstico rápido

Las tres formas de error

Error de plan: 402 y 404

Respuesta 402

Respuesta 404 sin cuerpo

Errores de factores

Errores comunes de la API

Errores de permisos y contexto

Errores de OAuth

Límite de envíos: 429

Cómo reintentar

Qué sigue

Autenticación con OAuth 2.0 y OIDC

Factores de autenticación en la API

Cuentas, identidades y contraseñas

FREE y plan pago