Diagnóstico de errores

Cada respuesta trae un request_id. Con él ves qué pasó con la llamada, qué eventos causó y si tus webhooks llegaron — tú, tu soporte o un asistente de IA.

Toda respuesta de KUTI trae el header X-Request-Id (req_…) y, si falló, también error.request_id y error.correlation_id. Si envías tu propio X-Request-Id (por ejemplo el id de tu pedido), KUTI lo devuelve como correlation_id para que unas la llamada con tus logs.

Errorjson

{
  "success": false,
  "message": "Validation failed.",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "request_id": "req_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "correlation_id": "pedido-1042"
  }
}

Qué puedes consultar

Pregunta	Endpoint
¿Qué pasó con esta llamada?	GET /diagnostics/requests/{request_id}
¿Qué llamadas hice para este pedido?	GET /diagnostics/requests?correlation_id=…
¿Qué le pasó a este cobro?	GET /diagnostics/payment-intents/{id}/trace
¿Por qué no llegó este webhook?	GET /webhook-deliveries/{id}

Usa una API key de Solo lectura (permiso diagnostics:read) para asistentes de IA. Solo ve lo de tu negocio y del modo de la clave; las llamadas se guardan 30 días en prueba y 90 en producción. Nunca se guardan bodies ni headers de tus llamadas.

event.request

Cada evento (y cada webhook) trae request: { id, idempotency_key } con la llamada tuya que lo originó, o null si lo generó el sistema (un pago confirmado, un vencimiento).