> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deltalead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de error y diagnóstico de la API REST de DeltaLead

> Los errores de la API de DeltaLead usan códigos de estado HTTP estándar y devuelven un cuerpo JSON con un código legible por máquina y un mensaje descriptivo.

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:

```json theme={null}
{
  "error": {
    "code": "lead_not_found",
    "message": "No lead found with the given ID.",
    "status": 404
  }
}
```

<ResponseField name="error.code" type="string">
  Identificador estable y legible por máquina del error. Este es el campo a usar en la lógica de manejo de errores.
</ResponseField>

<ResponseField name="error.message" type="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.
</ResponseField>

<ResponseField name="error.status" type="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).
</ResponseField>

## Códigos de estado HTTP

| Estado                      | Significado                                                             |
| --------------------------- | ----------------------------------------------------------------------- |
| `200 OK`                    | La solicitud fue exitosa                                                |
| `201 Created`               | Recurso creado correctamente                                            |
| `400 Bad Request`           | Parámetros inválidos: revisar `error.code` y `error.message`            |
| `401 Unauthorized`          | Clave de API ausente o inválida                                         |
| `403 Forbidden`             | Clave válida pero permisos insuficientes o cuenta suspendida            |
| `404 Not Found`             | El recurso no existe                                                    |
| `409 Conflict`              | Conflicto de recurso (por ejemplo, teléfono de lead duplicado)          |
| `422 Unprocessable Entity`  | Falló la validación: revisar `error.details` para los errores por campo |
| `429 Too Many Requests`     | Límite de tasa superado: reintentar después de `X-RateLimit-Reset`      |
| `500 Internal Server Error` | Error del servidor de DeltaLead: reintentar con backoff exponencial     |

## 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.

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed.",
    "status": 422,
    "details": [
      { "field": "phone", "message": "Phone number must be in E.164 format." }
    ]
  }
}
```

<ResponseField name="error.details" type="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.
</ResponseField>

Causas habituales de un `422`:

* Números de teléfono que no están en [formato E.164](https://en.wikipedia.org/wiki/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.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 14
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718294460
```

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](https://status.deltalead.ai) o contactar a soporte.

<Tip>
  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.
</Tip>