Saltar a contenido

Errores

Todo error de /v1 tiene la misma forma, incluidos los que produce la verificación de la credencial:

{ "error": { "code": "forbidden", "message": "…", "request_id": "…", "details": {} } }
  • code es el vocabulario cerrado sobre el que debe bifurcar tu cliente.
  • message es para un humano leyendo un log — no es estable entre versiones.
  • details es diagnóstico, no forma parte del contrato.
  • request_id coincide con la cabecera de respuesta X-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).