Errores

Todo error de la API llega con el mismo sobre JSON: un code estable pensado para tu código, un message en español pensado para personas y, cuando aporta, un details con contexto adicional. Programa siempre contra el code — los mensajes pueden cambiar de redacción; los códigos no.

¿Un rechazo que no esperabas? Antes de escribir a soporte, revisa el code: en la Partner API casi todos los 401/403 corresponden a una de las cuatro puertas de acceso y se resuelven desde la consola del colegio, no desde tu código.

El sobre de error

Nombre
error.code
Tipo
string
Descripción
Código estable en mayúsculas, por ejemplo PARTNER_DPA_NOT_ACTIVE. Es el contrato: úsalo para ramificar tu manejo de errores.
Nombre
error.message
Tipo
string
Descripción
Descripción legible, en español (es-CL) para los códigos del catálogo. Apta para mostrar en pantalla, pero no para parsear.
Nombre
error.details
Tipo
object | array
Descripción
Contexto opcional. En un VALIDATION_ERROR trae la lista de problemas del payload (campo por campo, formato de issues de Zod); en un PARTNER_RATE_LIMITED trae limit, windowSeconds y retryAfterSeconds.

Ejemplo: 403

{
  "error": {
    "code": "PARTNER_DPA_NOT_ACTIVE",
    "message": "El contrato de tratamiento de datos (DPA) no está vigente.",
    "details": {
      "organizationPartnerConnectionId": "…",
      "partnerAccountId": "…"
    }
  }
}

Ejemplo: 422 de validación

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Los datos enviados no son válidos. Revisa el formulario.",
    "details": [
      {
        "origin": "string",
        "code": "too_small",
        "minimum": 2,
        "inclusive": true,
        "path": ["targetSubjectReferenceCode"],
        "message": "Too small: expected string to have >=2 characters"
      }
    ]
  }
}

Códigos de autenticación y autorización de la Partner API

Estos son los códigos que produce la cadena de acceso de las rutas /partner/v1/..., en el orden en que se evalúan. Cada denegación queda además registrada en la auditoría del colegio.

Nombre
ORGANIZATION_ID_REQUIRED
Tipo
422
Descripción
La ruta requiere el parámetro :organizationId y no venía en la URL. Es lo primero que se verifica.
Nombre
PARTNER_BEARER_REQUIRED
Tipo
401
Descripción
Falta el encabezado Authorization: Bearer, está malformado, o enviaste x-api-key a una ruta de partner. Las rutas de partner solo aceptan la credencial Bearer.
Nombre
PARTNER_CREDENTIAL_INVALID
Tipo
401
Descripción
La credencial no existe, no coincide con ningún hash registrado o fue revocada.
Nombre
PARTNER_CREDENTIAL_EXPIRED
Tipo
401
Descripción
La credencial tenía fecha de expiración y ya pasó. Emite una nueva desde la consola.
Nombre
PARTNER_CONNECTION_NOT_ACTIVE
Tipo
403
Descripción
No existe una conexión activa entre tu cuenta de partner y la organización de la URL: el colegio no la ha creado, la pausó o la terminó.
Nombre
PARTNER_WORKSPACE_NOT_ACTIVE
Tipo
403
Descripción
Tu cuenta de partner está suspendida o pendiente de activación en Edugoverna, lo que deshabilita el acceso por API a todos tus colegios conectados.
Nombre
PARTNER_DPA_NOT_ACTIVE
Tipo
403
Descripción
La conexión no tiene un contrato de encargo de datos (DPA) ejecutado y vigente — o, en conexiones de registro externo, falta la declaración jurada del registrador.
Nombre
PARTNER_RATE_LIMITED
Tipo
429
Descripción
La credencial agotó su ventana de tasa. Se evalúa antes que el permiso y el alcance. La respuesta incluye Retry-After y details.retryAfterSeconds. Ver Límites.
Nombre
PARTNER_PERMISSION_REQUIRED
Tipo
403
Descripción
La credencial no lleva el permiso partner.* que la ruta exige. Los permisos se fijan al emitir la credencial.
Nombre
PARTNER_SCOPE_REQUIRED
Tipo
403
Descripción
La conexión con ese colegio no otorga el alcance de la ruta (por ejemplo consents:write). El colegio puede otorgarlo desde la consola.
Nombre
PARTNER_WORKSPACE_REQUIRED
Tipo
403
Descripción
La ruta opera sobre el espacio de trabajo propio del partner (por ejemplo campañas compartidas) y la organización de la URL no es tu workspace.

Códigos de dominio frecuentes

Superada la cadena de acceso, los errores restantes describen el recurso o el payload:

Nombre
VALIDATION_ERROR
Tipo
422
Descripción
El cuerpo o la query no pasan la validación de esquema. details enumera los problemas campo por campo.
Nombre
INVALID_CURSOR
Tipo
422
Descripción
El cursor de paginación no es válido, o se reutilizó con otros filtros u otra organización. Ver Paginación.
Nombre
PARTNER_SUBJECT_NOT_FOUND
Tipo
404
Descripción
Ningún titular del colegio tiene el referenceCode indicado.
Nombre
PARTNER_SUBJECT_TYPE_CONFLICT
Tipo
409
Descripción
El referenceCode existe, pero pertenece a un titular de otro tipo (por ejemplo, esperabas un estudiante y es un apoderado). details indica el tipo esperado y el real.
Nombre
SUBJECT_NOT_FOUND
Tipo
404
Descripción
El titular no existe o no es visible para tu conexión.
Nombre
CONSENT_REQUEST_NOT_FOUND
Tipo
404
Descripción
La solicitud de consentimiento no existe en esa organización.
Nombre
CONSENT_REQUEST_NOT_OPEN
Tipo
409
Descripción
La solicitud ya no está pendiente (decidida, revocada, invalidada o vencida): no se puede reemitir su enlace.
Nombre
CONSENT_DELIVERY_NOT_FOUND
Tipo
404
Descripción
La entrega no pertenece a esa solicitud.
Nombre
INTEGRATIONS_MODULE_REQUIRED
Tipo
409
Descripción
La organización no tiene el módulo integrations: no se pueden crear ni activar endpoints de webhook. Ver Webhooks.
Nombre
PROCESSING_ACTIVITY_NOT_FOUND
Tipo
404
Descripción
La actividad de tratamiento (o la versión indicada) no existe.
Nombre
NOT_FOUND
Tipo
404
Descripción
La ruta solicitada no existe: es el 404 genérico del router. Revisa el método y la URL.
Nombre
INTERNAL_SERVER_ERROR
Tipo
500
Descripción
Error inesperado del servidor. Reintenta con retroceso exponencial; si persiste, contacta a soporte con la hora y la ruta.

Cada grupo de endpoints documenta además sus códigos específicos — por ejemplo CONSENT_CAMPAIGN_CLOSED o RIGHTS_REQUEST_NOT_FOUND — en su página de la referencia.

Códigos del motor de riesgo

Los produce el registro de riesgos y los escenarios de las evaluaciones de impacto. Son rechazos de vocabulario y de regla metodológica, no de esquema: el payload puede ser sintácticamente válido y aun así no describir algo que la ley acepte.

Nombre
RISK_ENTRY_SUBJECT_INVALID
Tipo
422
Descripción
Algún valor de affectedSubjectTypes no es un tipo de titular conocido (student, guardian, staff, other). details.unknown los enumera.
Nombre
RISK_ENTRY_DATA_CATEGORY_INVALID
Tipo
422
Descripción
El dataCategoryGroup de la entrada no está en el catálogo de categorías del registro de riesgos.
Nombre
NNA_IMPACT_JUSTIFICATION_REQUIRED
Tipo
422
Descripción
Una fila redactada a mano (origin: "manual", el valor por defecto) califica el impacto bajo Significativo (3) afectando a estudiantes con datos sensibles, y no trae impactRationale. El interés superior del NNA (Art. 16 quáter) exige fundamentar por escrito una calificación así. Con origin: "template" o "suggested" no se rechaza: la fila se guarda y la respuesta trae warnings: ["nna_impact_floor"].
Rige en los dos lados del motor, y cada uno determina la sensibilidad donde corresponde: un escenario de EIPD la hereda de la actividad evaluada (involvesSensitiveData), mientras que una entrada del registro de riesgos la declara ella misma con su dataCategoryGroup — health_pie, socioeconomic, behavioral_convivencia o biometric_image—, porque describe un proceso y no una actividad de la que heredar.

Códigos del modelo de prevención

Los produce el modelo de prevención, un módulo add-on: sin contratarlo, sus rutas responden 403 MODULE_NOT_LICENSED antes que cualquiera de estos.

Nombre
MPI_REQUIREMENT_NOT_ATTESTABLE
Tipo
422
Descripción
La clave del requisito corresponde a uno derivado de los registros (responsable, delegado, caracterizacion, riesgos, protocolos), que se computa en lectura y no se puede declarar a mano.
Nombre
MPI_EVIDENCE_FILE_REQUIRED
Tipo
422
Descripción
El multipart/form-data llegó sin file, o el archivo venía vacío.
Nombre
MPI_EVIDENCE_TOO_LARGE
Tipo
400
Descripción
El documento de respaldo supera los 15 MB.
Nombre
MPI_EVIDENCE_NOT_FOUND
Tipo
404
Descripción
La declaración no tiene evidencia adjunta, o el artefacto referido no pertenece a la organización.
Nombre
MPI_DOSSIER_NOT_FOUND
Tipo
404
Descripción
No existe una versión sellada del expediente con ese id en la organización.
Nombre
MPI_DOSSIER_DOCUMENT_MISSING
Tipo
404
Descripción
La versión sellada existe pero no tiene documento generado.

Cómo reintentar

429: espera lo que indique el encabezado Retry-After (o details.retryAfterSeconds) antes de reintentar. No acortes la espera: la ventana no se reinicia antes.
5xx: reintenta con retroceso exponencial y jitter (por ejemplo 1 s, 2 s, 4 s…), con un tope de intentos. Las operaciones de escritura que aceptan idempotencyKey — como la creación de solicitudes y campañas de consentimiento — pueden reintentarse con la misma clave sin riesgo de duplicar.
4xx (salvo 429): no reintentes sin cambiar algo. Un 401/403 se resuelve en la consola del colegio; un 422 se resuelve corrigiendo el payload.