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
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ó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.