Verificación y problemas habituales - API REST

Un evento de prueba controlado

curl -X POST https://dockray.io/api/v1/PROJECT_TOKEN/project \
  -H 'Authorization: Bearer PROJECT_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"exception":{"values":[{"type":"RuntimeException","value":"Mensaje de control DockRay"}]}}'

Una respuesta 200 {"success": true} significa que el evento se guardó. Comprueba el panel, en la sección Errores del proyecto al que apunta el token.

Problemas habituales

401 en lugar de un evento guardado

No había clave en ninguno de los tres sitios: la URL, el campo de formulario ni la cabecera Authorization. Esa es la única causa de un 401; el código no dice nada sobre si la clave habría sido válida.

404 pese a una dirección aparentemente correcta

Hay una clave, pero no coincide con el proyecto de la URL: fue revocada, pertenece a otro proyecto, o el proyecto está deshabilitado en el panel. La respuesta es idéntica cuando el token de la URL directamente no existe - es intencionado, para no revelar qué proyectos hay realmente en la base de datos.

200 {"success": false} confundido con éxito

Esta respuesta tiene dos causas independientes: se agotó el cupo mensual de errores (ver más abajo), o al cuerpo le falta un campo obligatorio - exception.values[0].type y .value en un error, un contexts.trace.data no vacío en una transacción. Comprueba la forma del payload antes de sospechar del cupo.

Un cuerpo comprimido con gzip pierde la clave

Cuando envías un cuerpo con la cabecera Content-Encoding: gzip, un campo de formulario con la clave dentro de ese cuerpo nunca se lee: el analizador lee el flujo comprimido directamente como JSON, sin descomprimirlo en busca de campos de formulario. Mueve la clave a la URL o a la cabecera Authorization.

Una transacción vuelve con {"success": false}

Lo más habitual es que falte contexts.trace.data o esté vacío - es el único campo obligatorio de un informe de transacción.

Un mismo error se parte en muchas entradas

La huella se calcula con type y value. Un identificador de registro incrustado en el texto del mensaje parte un error en mil filas - muévelo al contexto de la petición o a la pila de llamadas.

Las peticiones terminan en un 429

Es el límite de peticiones por minuto y token de proyecto (1200 por defecto), independiente del cupo mensual de errores - suele significar un cliente en bucle o reintentos enviados sin esperar.

El panel responde 200 pero no aparece el evento

Una respuesta 200 {"success": false} significa que la cuenta ha agotado su cupo mensual de errores. La integración no lo trata como una avería, y hace bien. El cupo se ve en el panel de la cuenta; hasta fin de mes se calcula a partir del consumo registrado, así que borrar errores no lo reinicia.

Sigue sin funcionar

Repasa la lista de comprobación de falta de datos y, si no ayuda, escríbenos. Indica el nombre del proyecto, la versión de la integración y la hora aproximada de la prueba: acorta el camino a la respuesta.