Invalidar Verificación (OTP)

Invalida la verificación activa del número (el código vigente deja de servir). No envía ningún mensaje. Útil para limpiar el estado antes de un nuevo ciclo o al dar de baja un flujo.

delete/v2/otp

Este endpoint no envía ningún mensaje. Invalida el código vigente y borra el estado de verificación del número, dejándolo en none. El siguiente POST /v2/otp inicia un ciclo limpio.

Casos típicos: cancelar un flujo a petición del usuario, limpiar el estado tras un cambio de número, o resetear escenarios en tus pruebas automatizadas.

Autorización

apikeystringheaderrequerido

Cuerpo de la petición

application/json

phone_numberstringrequerido

Número cuya verificación quieres invalidar.

country_codestringrequerido

Código de país, numérico. Para México envía 52.

Respuesta

200Verificación invalidada

successbooleanrequerido

stateenumrequerido

Ya no hay verificación activa para el número.

enum:none

actionenumrequerido

enum:deleted

messagestring

hintstring

nextarray<string>

request_idstring

UUID para seguimiento de la petición.

400Parámetro faltante o inválido

successbooleanrequerido

stateenum

Estado actual de la verificación (presente cuando es relevante para el error).

enum:nonependingverifiedexpiredlocked

errorstringrequerido

Slug estable del error, para manejo programático:

Slug	HTTP	Significado
`otp_missing_param`	`400`	Falta un parámetro obligatorio.
`otp_invalid_param`	`400`	Un parámetro es inválido o no aplica a este endpoint.
`otp_invalid_channel`	`400`	`channel` debe ser `sms`, `whatsapp` o `voice`.
`otp_message_invalid`	`400`	El `message` personalizado no cumple las reglas (placeholders, GSM-7, 160).
`otp_incorrect_code`	`401`	El código no coincide.
`otp_insufficient_credits`	`402`	Saldo insuficiente para enviar.
`otp_not_found`	`404`	No hay verificación activa para el número.
`otp_already_verified`	`409`	El número ya está verificado.
`otp_code_expired`	`410`	El código expiró.
`otp_throttled`	`429`	Cooldown de reenvío activo (espera `resend_available_in`).
`otp_max_attempts`	`429`	Se agotaron los 7 intentos de verificación de la ronda.
`otp_internal`	`500`	Error inesperado.
`otp_send_failed`	`502`	El mensaje no pudo enviarse.

messagestringrequerido

Descripción del error en español.

hintstring

Sugerencia accionable para resolverlo.

nextarray<string>

Endpoints sugeridos como siguiente paso.

expires_atstring

Expiración del código vigente, cuando aplica.

attempts_remaininginteger

Intentos de verificación restantes, cuando aplica.

resend_available_ininteger

Segundos restantes del cooldown de reenvío, cuando aplica (errores otp_throttled).

codestring

Solo en otp_insufficient_credits: siempre sms_07, el código estándar de saldo insuficiente de toda la API.

request_idstring

UUID para seguimiento de la petición.

500Error interno inesperado

successbooleanrequerido

stateenum

Estado actual de la verificación (presente cuando es relevante para el error).

enum:nonependingverifiedexpiredlocked

errorstringrequerido

Slug estable del error, para manejo programático:

Slug	HTTP	Significado
`otp_missing_param`	`400`	Falta un parámetro obligatorio.
`otp_invalid_param`	`400`	Un parámetro es inválido o no aplica a este endpoint.
`otp_invalid_channel`	`400`	`channel` debe ser `sms`, `whatsapp` o `voice`.
`otp_message_invalid`	`400`	El `message` personalizado no cumple las reglas (placeholders, GSM-7, 160).
`otp_incorrect_code`	`401`	El código no coincide.
`otp_insufficient_credits`	`402`	Saldo insuficiente para enviar.
`otp_not_found`	`404`	No hay verificación activa para el número.
`otp_already_verified`	`409`	El número ya está verificado.
`otp_code_expired`	`410`	El código expiró.
`otp_throttled`	`429`	Cooldown de reenvío activo (espera `resend_available_in`).
`otp_max_attempts`	`429`	Se agotaron los 7 intentos de verificación de la ronda.
`otp_internal`	`500`	Error inesperado.
`otp_send_failed`	`502`	El mensaje no pudo enviarse.

messagestringrequerido

Descripción del error en español.

hintstring

Sugerencia accionable para resolverlo.

nextarray<string>

Endpoints sugeridos como siguiente paso.

expires_atstring

Expiración del código vigente, cuando aplica.

attempts_remaininginteger

Intentos de verificación restantes, cuando aplica.

resend_available_ininteger

Segundos restantes del cooldown de reenvío, cuando aplica (errores otp_throttled).

codestring

Solo en otp_insufficient_credits: siempre sms_07, el código estándar de saldo insuficiente de toda la API.

request_idstring

UUID para seguimiento de la petición.

Si no había verificación activa, la respuesta sigue siendo 200 con action: deleted — la operación es idempotente desde el punto de vista de tu integración: después de llamarla, el estado del número siempre es none.

Los errores de autenticación (auth_*) vienen de la capa común de la API y llegan con HTTP 200 y el detalle en el body — consulta Errores y límites.