Configuración - API REST
Respuestas
| Respuesta | Significado |
|---|---|
200 {"success": true} | el evento se guardó |
200 {"success": false} | la cuenta ha agotado su cupo mensual de errores o al cuerpo le faltaba un campo obligatorio - ambos casos se ven iguales desde fuera |
401 {"message": "Unauthenticated."} | la petición no llevaba clave en ninguno de los tres sitios |
404 {"message": "Project not found."} | la clave no coincide con el proyecto de la URL, el proyecto está deshabilitado, o el proyecto realmente no existe |
Un 404 no dice deliberadamente cuál de los tres motivos fue - la respuesta no debe revelar si un token de proyecto dado existe siquiera.
Agrupación de errores
El panel agrupa los eventos por la huella sha256(token del proyecto + type + value) y mantiene una fila por error y día, con un contador de apariciones. Por eso type y value deben mantenerse estables entre llamadas del mismo error: un número de pedido o un identificador de usuario incrustado en value parte un error en mil filas separadas. Deja la parte variable en el contexto - la URL de la petición, los datos del usuario o los fotogramas de la pila - no en el texto del mensaje.
Nombres de transacción
El campo transaction debería llevar el patrón de la ruta, como GET /orders/{order}, no GET /orders/8123. De lo contrario, la lista de transacciones del panel se parte en tantas filas como identificadores concretos hubiera.
Límite de peticiones
El ingest permite 1200 peticiones por minuto por token de proyecto (thor.ingest.throttle_per_minute) - una válvula de seguridad contra un cliente en bucle, no un cupo de negocio. Es independiente del cupo mensual de errores: superarlo termina en un 429, no en un 200 {"success": false}. Las peticiones también tienen un tope de tamaño de cuerpo, 2 MB por defecto.
Datos que no deberías enviar
A diferencia de las bibliotecas propias de DockRay, la API REST no filtra nada por sí misma: tu integración decide qué va en request.headers y en los campos user. No envíes Authorization, Cookie ni ninguna otra cabecera que lleve un secreto. Adjunta la IP, el correo o el nombre de usuario solo cuando de verdad los necesites para el diagnóstico: son datos personales, no metadatos técnicos.
Proteger la clave privada
La clave privada es un secreto del proyecto, no un identificador. Guárdala en variables de entorno, en un gestor de secretos o en la configuración del servidor: nunca en el repositorio, en los registros, en una captura de pantalla ni en código que llegue al navegador. Un proyecto puede tener varias claves, así que producción y preproducción deberían tener la suya: cada una se revoca por separado sin interrumpir a las demás. La sospecha de que una clave se ha filtrado ya es motivo suficiente para revocarla y generar otra.