Skip to main content
La API de DeltaLead usa códigos de estado HTTP estándar para señalar el resultado de cada solicitud. Cuando una solicitud falla, la respuesta siempre incluye un cuerpo JSON con dos campos garantizados: code (una cadena estable y legible por máquina) y message (una descripción legible de lo que salió mal). La lógica de manejo de errores debe ramificar según code, no según message, que puede cambiar entre versiones de la API.

​
Formato de la respuesta de error

Todas las respuestas de error siguen esta forma:
​
string
Identificador estable y legible por máquina del error. Este es el campo a usar en la lógica de manejo de errores.
​
string
Descripción legible del error, pensada para logging y depuración. No conviene depender de este valor de forma programática: puede cambiar sin aviso.
​
integer
El código de estado HTTP, replicado dentro del cuerpo por conveniencia cuando el código de estado externo no está disponible (por ejemplo, en algunos contextos de proxy o de logging).

​
Códigos de estado HTTP

​
Errores de validación (422)

Cuando falla la validación del cuerpo de la solicitud, la API devuelve una respuesta 422 con un arreglo adicional details que indica con precisión qué campos son inválidos. Recorrer details permite mostrar mensajes por campo a los usuarios o en los logs.
​
array
Presente solo en respuestas 422. Cada elemento contiene una clave field (la ruta dentro del cuerpo de la solicitud que falló) y una clave message que describe la regla de validación incumplida.
Causas habituales de un 422:
  • Números de teléfono que no están en formato E.164 (por ejemplo, +5491122334455 es válido; 011 2233-4455 no)
  • Campos obligatorios ausentes en el cuerpo de la solicitud
  • Valores de enumeración fuera del conjunto permitido (por ejemplo, un valor de status no reconocido)
  • Cadenas de fecha y hora que no siguen el formato ISO 8601

​
Límite de tasa (429)

Al superar las 1.000 solicitudes por minuto, la API devuelve 429 Too Many Requests. La respuesta incluye una cabecera Retry-After que indica cuántos segundos esperar antes de reintentar.
Conviene implementar backoff exponencial en todas las solicitudes que se reintentan: esperar los segundos indicados en Retry-After en el primer reintento y luego duplicar el tiempo de espera en cada intento posterior (con un tope máximo, por ejemplo 60 segundos), hasta que la solicitud tenga éxito o se agote el presupuesto de reintentos.

​
Errores de servidor (500)

Un 500 Internal Server Error indica una falla transitoria en la infraestructura de DeltaLead. Corresponde reintentar la solicitud con backoff exponencial: la gran mayoría de los errores transitorios se resuelve en pocos segundos. Si un 500 persiste durante más de unos minutos, se puede consultar la página de estado de DeltaLead o contactar a soporte.
Conviene registrar siempre el cuerpo completo de la respuesta de error, no solo el código de estado HTTP. El campo error.code es legible por máquina y estable entre versiones de la API, lo que lo hace apto para reglas de alerta y remediación automática. Por ejemplo, se puede detectar lead_not_found y omitir el registro, o capturar validation_error y mostrar error.details directamente en el panel de un operador.