Errores¶
Todo error de /v1 tiene la misma forma, incluidos los que produce la verificación de la
credencial:
codees el vocabulario cerrado sobre el que debe bifurcar tu cliente.messagees para un humano leyendo un log — no es estable entre versiones.detailses diagnóstico, no forma parte del contrato.request_idcoincide con la cabecera de respuestaX-Request-Id; incúyelo si nos escribes por soporte.
Vocabulario de code¶
error.code |
HTTP | Cuándo |
|---|---|---|
invalid_request |
400 | La petición no cumple el esquema esperado |
unauthorized |
401 | Clave desconocida, mal formada, revocada o caducada — misma respuesta para las cuatro |
forbidden |
403 | Falta un ámbito (details.missing dice cuál), o tu inquilino no tiene una licencia en vigor — ninguna, suspendida, revocada o caducada (details.code es LICENCE_INACTIVE y details.licence dice cuál). Un token nuevo no arregla lo segundo: renueva la licencia en la consola. También details.code MODULE_NOT_ENTITLED cuando la credencial lleva el ámbito pero el inquilino no tiene activo su módulo (details.scopes, details.modules y details.frameworks para un marco de cumplimiento en el plan pero no activado); una clave nueva no lo arregla. Y details.code IP_NOT_ALLOWED cuando el inquilino tiene una lista de IP permitidas y la petición llega desde una dirección fuera de ella; el administrador del inquilino añade la dirección. Y details.code MFA_ENROLLMENT_REQUIRED para un token de acceso OAuth (CLI, cliente MCP) cuya cuenta no ha dado de alta el segundo factor que exige el inquilino; da de alta uno en la consola e inicia sesión de nuevo. En una escritura (alerts:write), también details.code ROLE_NOT_PERMITTED (el rol del usuario que creó la clave no permite este cambio) o WRITE_ACTOR_UNRESOLVED (ese usuario ya no existe, está suspendido o ya no alcanza el inquilino), y LICENCE_INACTIVE mientras la licencia está en su periodo de gracia. Y details.code PLAN_WITHOUT_API (con details.deniedReason plan_without_api) cuando el plan de tu inquilino no incluye acceso a la API, que empieza en Comply, salvo en Gobierno IA (también durante la prueba); una clave o un token nuevos no lo cambian; el acceso a la API está incluido a partir de Comply, salvo en Gobierno IA, y el plan se puede cambiar en la consola |
not_found |
404 | El recurso no existe, o la ruta no existe |
method_not_allowed |
405 | Un método que la ruta no sirve (toda ruta sirve GET salvo las dos escrituras de alertas, que sirven POST); la cabecera Allow indica los permitidos |
conflict |
409 | En una escritura de alerta: details.code ALERT_RESOLVED (la alerta ya está resuelta) o ALERT_STATE_CHANGED (cambió entre la lectura y la escritura; vuelve a leerla). En GET /v1/reports/{id}/download: el fichero no puede servirse como se pide. details.code es REPORT_NOT_READY (aún se genera o falló; details.status), FORMAT_UNSUPPORTED (no hay renderizador para ese formato; details.formats lista los que hay) o FILE_TOO_LARGE (supera el tamaño máximo; details.limit_bytes). Ver Autenticación |
rate_limited |
429 | Cuota superada; details.scope indica si fue por clave, por inquilino o por servicio (write_key es el presupuesto de escritura de una clave) |
internal_error |
500 | Error inesperado del servidor |
service_unavailable |
503 | Servicio temporalmente no disponible |
Reintentos¶
Para 429, 500, 502, 503 y 504, reintenta con backoff exponencial y respeta la
cabecera Retry-After cuando esté presente. No reintentes automáticamente sobre 400,
401, 403, 404 o 405: la petición está mal formada o no tiene permiso, y repetirla sin
cambios produce el mismo error. Un 409 REPORT_NOT_READY con details.status generating
merece reintentarse más tarde; los demás 409 no (ALERT_STATE_CHANGED: lee antes la alerta otra vez).