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

# Depurar tu integración

> Encuentra por qué falló una request a la API de Timbrix usando el request log y el header X-Request-Id.

Cada request que haces con una API key queda en el **request log** durante 30 días. Con él puedes ver qué se envió, qué respondió la API y, si fue rechazada, por qué.

## Dónde verlo en la web

Entra a **Actividad API → Request log**, en la barra lateral bajo **Configurar**. Solo lo ven los usuarios con rol **owner** o **admin**.

## Qué significa cada rechazo

Cuando una request con una llave que sí existe es rechazada, el log indica el motivo en `authFailure`:

| Motivo | Qué pasó | Qué hacer |
| - | - | - |
| `inactive` | La API key fue revocada | Crea una llave nueva y actualiza tu integración |
| `expired` | La API key llegó a su fecha de vencimiento | Crea una llave nueva |
| `ip_not_allowed` | La request llegó desde una IP que no está en la lista permitida | Agrega la IP de tu servidor a la llave |
| `missing_scope` | La llave no tiene el scope que pide el endpoint | Agrega el scope necesario a la llave |

También se registran los `429` (límite de requests) hechos con una llave conocida. Las requests con una llave desconocida no se registran.

## Filtrar por status y ruta

En la web usa los filtros de status (`2xx`, `4xx`, `5xx` o un código exacto), ruta, método, API key, entorno y canal. La ruta es la plantilla, por ejemplo `/invoices/:uuid`, así agrupas todas las consultas de facturas sin importar el UUID.

## Con la API

```bash theme={null}
curl "https://api.timbrix.mx/request-logs?status=5xx&route=/invoices" \
  -H "X-API-Key: sk_..."
```

La llave necesita el scope `read:request-logs`. Por defecto devuelve las últimas 24 horas; el rango máximo es de 30 días.

## Con el SDK

```typescript theme={null}
import { Timbrix } from "@timbrix/sdk"

const client = new Timbrix({ apiKey: "sk_..." })

const { data, nextCursor } = await client.requestLogs.list({ status: "5xx" })
const detalle = await client.requestLogs.get(data[0].id)
```

## Con la CLI

```bash theme={null}
timbrix logs list --org <org-id> --status 5xx --since 24h
timbrix logs get <request-id> --org <org-id>
```

La CLI usa tu sesión de `timbrix login` junto con `--org` (debes ser owner o admin de la organización), no una API key.

`logs list` acepta `--since` (`1h`, `24h`, `7d`, `30d`), `--status`, `--route`, `--key`, `--env`, `--limit`, `--cursor` y `--json`.

## Usar X-Request-Id

Cada respuesta de la API trae el header `X-Request-Id` (excepto en `/health`, `/docs` y las requests `OPTIONS`). Ese valor es el `id` del request log. Solo se guardan las requests hechas con una API key válida o atribuible, y pueden tardar unos segundos en aparecer. Así que:

1. Guarda el `X-Request-Id` de las respuestas que fallen, junto con tus propios logs.
2. Búscalo con `GET /request-logs/{id}` o `timbrix logs get <id>` para ver el detalle, incluido el cuerpo del error.
3. Inclúyelo cuando escribas a [soporte](mailto:hola@timbrix.mx); con él podemos ubicar tu request de inmediato.

El detalle de un error (`errorBody`) solo se guarda para respuestas 400 o mayores, con los RFC enmascarados como `***RFC***` y un máximo de 2 KB.

## Lo que no se guarda

* Requests hechas desde el dashboard con sesión.
* Cuerpos de las requests y de las respuestas exitosas.
* Requests con una llave desconocida.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.