# [API FE DOM] Mejora de la documentación y unificación del formato de errores

## 🆕 Unificación del formato de errores y mejora en la documentación

### Fecha

**Disponible en sandbox**
Fecha tentativa de despliegue en producción: **3 de febrero de 2026**

### Tipo de cambio

**Cambio de contrato / Mejora de documentación**

***

### 📝 Descripción

A partir de esta versión se unifica y estandariza el **formato de respuesta de errores** de la API, con el objetivo de:

* Eliminar inconsistencias en las respuestas de error.
* Facilitar el manejo de errores por parte de integradores.
* Mejorar la trazabilidad y documentación de cada error mediante códigos únicos.

Este cambio viene acompañado de una **mejora en la documentación**, incorporando un **diccionario de errores** organizado por categorías.

> ⚠️ **Importante**
> Estos cambios se encuentran **disponibles únicamente en el ambiente de sandbox**, con el objetivo de que los integradores puedan **adaptar y validar sus implementaciones** con anticipación.

***

### 🔴 Comportamiento anterior

Anteriormente, las respuestas de error podían variar entre distintos formatos, por ejemplo:

```json
{ "code": 400, "message": ["error message"] }
```

```json
{ "code": 400, "errors": ["error message"] }
```

```json
{ "errors": ["error message"] }
```

Esta falta de uniformidad dificultaba el parseo automático y el manejo consistente de errores.

***

### ✅ Nuevo formato unificado de errores

A partir de este cambio, **todas las respuestas de error** seguirán el siguiente formato:

```json
{
  "code": 400,
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Error description in English",
      "field": "fieldName"
    }
  ]
}
```

***

### 📌 Detalle de los campos

* **code** (number)
  Código HTTP de la respuesta.

* **errors** (array)
  Lista de errores detectados durante el procesamiento de la request.

Cada objeto dentro de `errors` contiene:

* **code** (string)
  Identificador único del error.

* **message** (string)
  Descripción del error en **inglés**, orientada al diagnóstico técnico.

* **field** (string, opcional)
  Campo asociado al error, cuando aplica.
  Puede no enviarse si el error no está vinculado a un campo específico.

***

### 📚 Diccionario de errores

La documentación incorpora un **diccionario de errores**, organizado por categorías, entre ellas:

* [Validaciones asincrónicas de compañías](https://developer.alanube.co/v1.0-DOM/reference/companies)
* [Validaciones sincrónicas de compañías](https://developer.alanube.co/v1.0-DOM/reference/company-error-table)
* [Usuarios](https://developer.alanube.co/v1.0-DOM/reference/users)
* [DGII](https://developer.alanube.co/v1.0-DOM/reference/dgii)
* [Documentos](https://developer.alanube.co/v1.0-DOM/reference/documents)
* [Sets de prueba](https://developer.alanube.co/v1.0-DOM/reference/settest)
* [Acuses de recibo](https://developer.alanube.co/v1.0-DOM/reference/acknowledgments)
* [Validaciones de tipos](https://developer.alanube.co/v1.0-DOM/reference/typevalidations)
* [Validaciones de esquemas](https://developer.alanube.co/v1.0-DOM/reference/schemavalidations)
* [Validaciones comunes](https://developer.alanube.co/v1.0-DOM/reference/commonvalidations)
* [Identificación de documento](https://developer.alanube.co/v1.0-DOM/reference/id-doc-error-table)
* [Documentos de referencia](https://developer.alanube.co/v1.0-DOM/reference/information-reference-error-table)
* [Moneda](https://developer.alanube.co/v1.0-DOM/reference/other-currency-error-table)
* [Descuentos o recargos](https://developer.alanube.co/v1.0-DOM/reference/discounts-or-surcharges-error-table)
* [Errores generales](https://developer.alanube.co/v1.0-DOM/reference/general)
* [Configuración](https://developer.alanube.co/v1.0-DOM/reference/config-error-table)

> ℹ️ **Nota**
> La lista de errores documentada **no es exhaustiva**.
> Pueden incorporarse nuevos errores y categorías en el futuro sin requerir cambios en el formato de respuesta.

***

### ⚠️ Impacto para integradores

* Este cambio **modifica el contrato de respuesta de errores**.
* Los formatos anteriores quedan **deprecados**.
* Se recomienda:

  * Adaptar el manejo de errores para consumir el array `errors`.
  * Utilizar el `code` de cada error como referencia principal.
  * Realizar las validaciones necesarias en **sandbox** antes del pase a producción.

***

### 🚀 Despliegue a producción

* Fecha tentativa de despliegue: **3 de febrero de 2026**.
* En caso de que esta fecha se modifique, **se comunicará oportunamente a los integradores**.

***

### 📌 Estado

**Activo en sandbox** – Pendiente de despliegue a producción.