Verificar Código (OTP)

Comprueba el código que capturó el usuario. Si coincide, el número queda verificado (state: verified). Cada código admite 7 intentos; al agotarlos la verificación se bloquea (locked) hasta rotar el código con POST /v2/otp y code_rotate: true.

post/v2/otp/verify

Llama a este endpoint cuando el usuario capture el código que recibió. Envía el mismo phone_number y country_code que usaste al crear el código: si el status HTTP es 200, el número quedó verificado.

Autorización

apikeystringheaderrequerido

Cuerpo de la petición

application/json

phone_numberstringrequerido

El mismo número usado al enviar el código.

country_codestringrequerido

El mismo código de país usado al enviar. Para México 52.

codestringrequerido

El código que capturó el usuario.

Respuesta

200Código correcto: número verificado

successbooleanrequerido

stateenumrequerido

El número quedó verificado.

enum:verified

actionenumrequerido

enum:verified

messagestring

hintstring

Vacío en éxito: el flujo terminó.

nextarray<string>

Vacío en éxito: no hay siguiente paso.

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.

401Código incorrecto (quedan intentos)

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.

404No hay verificación activa para el número

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.

409El número ya está verificado

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.

410El código expiró

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.

429Intentos agotados: la verificación queda bloqueada (locked). Incluye header Retry-After.

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.

Intentos y bloqueo

Cada código admite 7 intentos de verificación. Al agotarlos, la verificación pasa a locked (HTTP 429) y la única salida es generar un código nuevo con POST /v2/otp y code_rotate: true. Muestra attempts_remaining al usuario para que sepa cuántos intentos le quedan, y no implementes reintentos automáticos.

Cómo leer los errores

El status HTTP distingue cada caso — puedes ramificar tu código directamente sobre él:

HTTP	`error`	Cuándo ocurre	Qué hacer
`401`	`otp_incorrect_code`	El código no coincide (quedan intentos).	Permite reintentar; la respuesta trae `attempts_remaining`.
`404`	`otp_not_found`	No hay verificación activa para el número.	Inicia el flujo con `POST /v2/otp`.
`409`	`otp_already_verified`	El número ya estaba verificado.	Trátalo como éxito, o invalida con `DELETE /v2/otp` para un nuevo ciclo.
`410`	`otp_code_expired`	El código venció.	Genera uno nuevo con `POST /v2/otp`.
`429`	`otp_max_attempts`	Se agotaron los 7 intentos de la ronda.	Rota el código: `POST /v2/otp` con `code_rotate: true`.
`400`	`otp_missing_param` / `otp_invalid_param`	Falta `code`, `phone_number` o `country_code`, o enviaste un parámetro que no aplica aquí.	El `hint` indica el parámetro exacto.

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.