Errores

Cada error dice qué pasó, con un código estable para tu código y un mensaje para las personas. Este catálogo se genera desde el de la API.

Formato

Todo 4xx y 5xx responde con application/problem+json (RFC 9457):

{
  "type": "https://docs.inalambria.com/verify/errors/20003",
  "title": "invalid_phone_number",
  "status": 400,
  "detail": "El número indicado no es un número móvil válido en formato E.164.",
  "code": 20003,
  "field": "to",
  "hint": "Incluye el indicativo de país precedido de '+'. Para Colombia: +57 seguido de 10 dígitos.",
  "request_id": "req_01J9XQ4M7KZ3T8V2W6N5P0QRST"
}

Las respuestas que se producen antes de que tu petición llegue a la API, como 404 por una ruta desconocida, 405, 413 por un cuerpo mayor de 16 KiB o 415 por un Content-Type que no es JSON, no traen code: para esas decide con status.

👍

Consejo

Un código incorrecto no es un error: responde 200 con status: "pending". Los errores quedan para peticiones que no se pudieron atender.

Qué reintentar

• 5xx: sí, con la misma Idempotency-Key y retroceso exponencial.
• 429: sí, después de esperar y con una Idempotency-Key nueva. Respeta Retry-After cuando viene.
• 409 con 20010: sí, después del Retry-After; la primera petición sigue en curso.
• Cualquier otro 4xx: no. Corrige la petición: repetirla dará el mismo resultado.

Autenticación (10000–10999)

La clave de API o el producto de la aplicación.

10001

HTTP 401

• invalid_api_key — La clave de API es inválida. Verificá que la clave enviada en el encabezado Authorization sea correcta y esté vigente.

10002

HTTP 401

• revoked_api_key — La clave de API fue revocada. Emití una nueva clave desde la consola; esta ya no puede usarse.

10003

HTTP 403

• api_key_ip_not_allowed — La clave de API no puede usarse desde esta dirección IP. Revisá las direcciones IP permitidas de la clave en la consola.

10010

HTTP 403

• product_not_enabled — La aplicación no tiene este producto habilitado. Contactá a soporte para habilitar el producto en esta aplicación.

10011

HTTP 401

• api_key_not_found — La clave de API indicada no existe o no pertenece a esta cuenta.

10013

HTTP 403

• channel_not_enabled — La aplicación tiene apagado el canal que hace falta para esta verificación. Revisá los canales encendidos de la aplicación en la consola de Verify.

Petición inválida (20000–20999)

El cuerpo o los encabezados no cumplen el contrato. Corrige la petición antes de reintentar.

20001

HTTP 400

• malformed_json — El cuerpo de la petición no es un JSON válido. Verificá que el cuerpo enviado sea JSON bien formado.

20002

HTTP 400

• sandbox_recipient_not_allowed — El destinatario no está permitido para el entorno autenticado. Utilice destinos documentados de prueba únicamente con claves test.
• missing_field — Falta un campo requerido en la petición.
• invalid_request_field — Un campo de la petición tiene un tipo inválido.
• idempotency_key_invalid — La cabecera Idempotency-Key es inválida. Debe tener entre 1 y 255 caracteres.
• malformed_code — El código enviado no tiene el formato esperado.
• resend_cooldown_out_of_range — La configuración de reenvío de la aplicación está fuera de rango.
• channel_timeout_out_of_range — El tiempo de espera del canal configurado está fuera de rango.

20003

HTTP 400

• invalid_phone_number — El número indicado no es un número móvil válido en formato E.164. Incluye el indicativo de país precedido de '+'. Para Colombia: +57 seguido de 10 dígitos.

20004

HTTP 400

• invalid_email — La dirección de correo indicada no es válida.

20005

HTTP 400

• channel_incompatible_with_recipient — El canal indicado no es compatible con el tipo de destinatario. Los canales whatsapp/sms requieren un teléfono; email requiere una dirección de correo.

20006

HTTP 400

• cascade_too_long — La cascada de canales tiene más pasos de los permitidos.

20007

HTTP 400

• ttl_out_of_range — El tiempo de expiración solicitado está fuera de rango.

20009

HTTP 400

• code_length_out_of_range — La longitud de código solicitada está fuera de rango.

20010

HTTP 422, 409

• idempotency_key_reuse — La clave de idempotencia ya fue usada con un cuerpo distinto.
• idempotency_request_in_flight — Ya hay una petición en curso con esta clave de idempotencia. Reintentá luego del tiempo indicado en Retry-After.

20011

HTTP 400

• max_attempts_out_of_range — La cantidad máxima de intentos solicitada está fuera de rango.

20012

HTTP 400

• code_type_invalid — El tipo de código configurado no es válido.

20013

HTTP 400

• brand_invalid — El nombre de marca indicado no es válido. Debe tener hasta 64 caracteres y no contener caracteres de control.

20014

HTTP 400

• client_reference_invalid — La referencia de cliente indicada no es válida. Debe tener hasta 128 caracteres y no contener caracteres de control.

Estado de la verificación (30000–30999)

La verificación no existe o ya terminó.

30001

HTTP 404

• verification_not_found — La verificación indicada no existe.

30002

HTTP 409

• verification_terminal — La verificación ya alcanzó un estado final y no acepta más intentos.

Límites y antifraude (40000–40999)

La petición es válida pero no se atiende. El tráfico bloqueado no se factura.

40001

HTTP 429

• recipient_rate_limit_exceeded — Se superó el límite de solicitudes para este destinatario.

40002

HTTP 429

• application_rate_limit_exceeded — Se superó el límite de solicitudes para esta aplicación.

40003

HTTP 429

• ip_rate_limit_exceeded — Se superó el límite de solicitudes para esta dirección IP.

40004

HTTP 429 · Aún no se emite

• custom_key_rate_limit_exceeded — Se superó el límite de solicitudes para esta clave personalizada.

40005

HTTP 429

• api_key_rate_limit_exceeded — Se superó el límite de solicitudes por minuto de esta clave de API. Esperá el tiempo indicado en Retry-After antes de reintentar.

40006

HTTP 429

• sim_swap_rate_limit_exceeded — La aplicación superó su límite de consultas de SIM swap por minuto. Esperá un minuto antes de volver a consultar.

40010

HTTP 403 · Aún no se emite

• anti_fraud_blocked — La solicitud fue bloqueada por el motor antifraude.

40011

HTTP 403

• recipient_blocked — El destinatario está en la lista de bloqueo.

40012

HTTP 403

• country_not_enabled — El país del destinatario no está habilitado para esta aplicación.

40013

HTTP 403 · Aún no se emite

• preflight_denied — La solicitud fue denegada por la validación previa al envío.

40014

HTTP 403

• sim_swap_recent — La SIM del número cambió hace poco y la aplicación no envía códigos en ese caso. Verificá la identidad de la persona por otro medio antes de volver a intentarlo.

Plataforma (50000–50999)

Algo falló de nuestro lado. Reintenta con la misma Idempotency-Key.

50010

HTTP 500

• internal_error — Ocurrió un error interno. Intentá nuevamente más tarde.

50011

HTTP 503

• sim_swap_provider_unavailable — No se pudo consultar el cambio de SIM con el proveedor. Intentá nuevamente en unos minutos.