Panel SMS

Consultar Estado de Verificación (OTP)

Devuelve el estado actual de la verificación de un número sin efectos secundarios: no envía mensajes, no consume intentos, no reinicia nada. Úsalo para decidir qué mostrar en tu UI (habilitar el botón de reenvío, mostrar intentos restantes, etc.).
get/v2/otp/status

Consulta de solo lectura: no envía mensajes, no consume intentos, no altera el estado. Ideal para construir tu UI de verificación:

  • resend_available_in te dice cuándo habilitar el botón de "Reenviar código" (0 = ya disponible).
  • attempts_remaining te dice cuántos intentos mostrarle al usuario.
  • state te dice qué pantalla corresponde: captura de código (pending), éxito (verified), pedir código nuevo (expired, locked) o iniciar flujo (none).

Los parámetros van como query string (es un GET).

Autorización

apikeystringheaderrequerido

Parámetros de query

phone_numberstringrequerido
Número cuyo estado quieres consultar.
country_codestringrequerido
Código de país, numérico. Para México 52.

Respuesta

200Estado actual de la verificación
successbooleanrequerido
stateenumrequerido

Estado actual de la verificación para el número:

  • none: no hay verificación activa.
  • pending: hay un código vigente esperando verificación.
  • verified: el número ya fue verificado.
  • expired: el código venció sin verificarse.
  • locked: se agotaron los 7 intentos de verificación de la ronda.
enum:nonependingverifiedexpiredlocked
messagestring
hintstring
Sugerencia accionable según el estado.
nextarray<string>
Endpoints sugeridos como siguiente paso según el estado.
expires_atstring | null
Expiración del código vigente (YYYY-MM-DD HH:mm:ss). null si no hay verificación activa.
attempts_remaininginteger
Intentos de verificación restantes para el código vigente.
resend_available_ininteger
Segundos restantes del cooldown de reenvío. 0 = ya puedes reenviar.
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.

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.