# Estados y respuestas

> Qué responde la API cuando la DIAN valida, rechaza o no contesta (201, 202, 402, 422, 503) y cómo continuar sin duplicar documentos.

Fuente: https://platform.trevol.si/docs/respuestas

Trevol valida, numera, firma, envía a la DIAN y **responde apenas la DIAN valida** (la meta es 3 segundos o menos; en la prueba del 23 de octubre de 2026, en habilitación, la mediana fue 1,9 s).

## Qué responde

| HTTP                                                                          | Qué pasó                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 201                                                                           | La DIAN validó el documento (`status: accepted`).                                                                                                                                                                                                                                      |
| 422 [`dian_rejected`](/docs/errores#dian_rejected)                            | La DIAN lo rechazó; `document` trae el documento y sus reglas traducidas.                                                                                                                                                                                                              |
| 422 [`validation_error`](/docs/errores#validation_error)                      | Trevol lo rechazó antes de numerar: no se gastó nada.                                                                                                                                                                                                                                  |
| 402 [`insufficient_balance`](/docs/errores#insufficient_balance)              | Producción sin saldo: queda `pending` con su número.                                                                                                                                                                                                                                   |
| 202 `processing` (versión 2026-10-22)                                         | La DIAN no contestó. **Trevol termina el documento** (le pregunta por el CUFE y, si hace falta, lo reenvía) y te avisa por webhook con `….accepted`, `….rejected` o `….error`. **No crees otro documento para esa venta.** Trae `Location` y `Retry-After: 30`.                        |
| 202 `sending` (versión 2026-10-22)                                            | Otra petición, o el fondo, lo está enviando ahora. Igual que el anterior.                                                                                                                                                                                                              |
| 202 `validating` (las dos versiones)                                          | La propia DIAN responde después: el set de pruebas de habilitación de la nómina o del documento equivalente todavía valida el documento, o un evento RADIAN quedó en «en proceso de validación» (98). No es un error y **no se reenvía**: Trevol solo consulta y te avisa por webhook. |
| 503 [`dian_unavailable`](/docs/errores#dian_unavailable) (versión 2026-10-21) | La DIAN no contestó: reintenta con la misma `Idempotency-Key`. Trevol además lo verifica en segundo plano (solo consulta; no reenvía).                                                                                                                                                 |

Todos los errores están en el [catálogo de errores](/docs/errores).

## Un 202 no es un error

```http respuesta
HTTP/1.1 202 Accepted
Location: /v1/invoices/inv_08cd6774e31e401c9fa0fbf92b3fbdc0
Retry-After: 30
Trevol-Version: 2026-10-22

{
  "id": "inv_08cd6774e31e401c9fa0fbf92b3fbdc0",
  "object": "invoice",
  "status": "processing",
  "number": "SETP994307052",
  "cufe": null,
  "dian": { "status_code": null, "rules": [] }
}
```

Un 202 ya tiene su `id` y su número. Para saber cómo terminó, **espera el webhook** o consulta el documento:

`GET /v1/invoices/{id}` (`retrieveInvoice`)

#### cURL

```bash
curl "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY"
```

[Probar en el Playground](https://platform.trevol.si/playground?op=retrieveInvoice)

Los SDK no reintentan un 202 ni lo convierten en excepción: lo devuelven como cualquier respuesta, con su `status`.

## Los estados de un documento

| `status`      | Significado                                                                              |
| ------------- | ---------------------------------------------------------------------------------------- |
| `pending`     | Numerado, sin enviar (por ejemplo, sin saldo).                                           |
| `sending`     | Se está enviando a la DIAN.                                                              |
| `processing`  | Solo en 2026-10-22: la DIAN no confirmó y Trevol lo resuelve.                            |
| `validating`  | Nómina, documento equivalente y eventos: la DIAN responde después, en las dos versiones. |
| `accepted`    | Validado por la DIAN.                                                                    |
| `rejected`    | La DIAN lo rechazó; se corrige con `PUT` y el mismo número.                              |
| `error`       | No se pudo enviar.                                                                       |
| `contingency` | Documento equivalente en contingencia.                                                   |

## Rechazos y correcciones

- **Rechazado por la DIAN:** corrige con `PUT` (cuerpo completo, nueva `Idempotency-Key`). Sale con el mismo número. Un rechazo no bloquea los demás envíos. Cada regla trae su explicación en español: [Reglas de la DIAN](/docs/errores/reglas-dian).
- **Pendiente o en error:** `POST …/send` lo vuelve a enviar (por ejemplo, después de recargar saldo).
- **Validado:** ya no se cambia; se corrige con una [nota crédito o débito](/docs/notas).