Errores y diagnóstico

Todos los errores tienen la misma forma:

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "Missing required scope: students:read.",
    "requestId": "..."
  }
}

Programa contra code, nunca contra message. El código es el contrato; el mensaje está para que lo lea una persona y puede cambiar.

Catálogo completo

Autenticación y acceso

Código	HTTP	Qué pasó	Qué hacer
`CLIENT_API_DISABLED`	403	El Client API no está habilitado en el entorno.	Revisar `EDTOOLS_CLIENT_API_ENABLED=1`. Es configuración de EdTools, no tuya.
`INVALID_TOKEN`	401	Token ausente o malformado.	Revisar la cabecera `Authorization: Bearer ...`.
`TOKEN_REVOKED`	401	La key fue revocada.	Pedir una nueva. Alguien la revocó a propósito.
`TOKEN_EXPIRED`	401	La key pasó su fecha de expiración.	Rotar. Y poner el recordatorio de rotación esta vez.
`TENANT_DISABLED`	403	La institución está deshabilitada.	No se resuelve por API: hablar con EdTools.
`IP_NOT_ALLOWED`	403	La IP de origen no está en la allowlist.	Agregar la IP o el CIDR de salida real del cliente. Ojo con los proxies.

Permisos

Código	HTTP	Qué pasó	Qué hacer
`SCOPE_REQUIRED`	403	Al token le falta el scope del endpoint.	Agregar el scope, o usar otro token. Ver Scopes.
`MODULE_DISABLED`	403	La institución no tiene ese módulo encendido.	Revisar `platform_integrations` y el módulo funcional. Ver Módulos.
`SOR_WRITE_FORBIDDEN`	403	Ese dominio de datos no admite escrituras de este token.	Revisar `sorByDomain` y `masterDomains` en `/me`. Ver Multi-tenancy.

Petición

Código	HTTP	Qué pasó	Qué hacer
`VALIDATION_ERROR`	400	El cuerpo o los parámetros no pasan el esquema.	El detalle dice qué campo. Contrastar con la Referencia.
`NOT_FOUND`	404	El recurso no existe en esta institución.	Verificar el id. Recuerda que el tenant sale del token.
`CONFLICT`	409	El estado actual no admite la operación.	Releer el recurso antes de reintentar.
`IDEMPOTENCY_KEY_REQUIRED`	400	Falta `Idempotency-Key` en un `POST` que la exige.	Ver Idempotencia.
`IDEMPOTENCY_CONFLICT`	409	Esa clave ya se usó con otro cuerpo, método o path.	Usar una clave nueva, o mandar exactamente la misma petición.
`RATE_LIMITED`	429	Se pasó del tope por minuto.	Esperar a `X-RateLimit-Reset`. Ver abajo.

Cualquier 5xx es problema de EdTools: guarda el requestId y repórtalo.

Rate limits

Toda respuesta autenticada trae el estado del tope:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1778284800

El tope es por token y por minuto. Si repartes el trabajo entre varios procesos con el mismo token, comparten el presupuesto.

Al recibir 429, espera hasta X-RateLimit-Reset (epoch en segundos) en vez de reintentar de inmediato. Para cargas grandes, pagina con page y limit y usa updatedSince para traer solo lo que cambió: casi siempre el problema no es el tope, es que estás pidiendo todo el catálogo cada hora.

Cuando toca pedir ayuda

En Ajustes → API e integraciones → Actividad se busca por path, API key, IP, user-agent o requestId. El detalle de cada llamada trae el endpoint, el scope exigido, el Source of Record, los módulos requeridos, el código de error y el estado del rate limit. Ahí mismo hay un resumen copiable pensado para compartir: no lleva payloads sensibles ni la cabecera Authorization.

Nunca mandes el token en un ticket, un chat o un correo. Para diagnosticar basta con requestId, el nombre de la key, el sistema de origen y la ventana horaria.

Empezar

La plataforma

Client API

Errores y diagnóstico

Catálogo completo

Autenticación y acceso

Permisos

Petición

Rate limits

Cuando toca pedir ayuda

​Catálogo completo

​Autenticación y acceso

​Permisos

​Petición

​Rate limits

​Cuando toca pedir ayuda

Catálogo completo

Autenticación y acceso

Permisos

Petición

Rate limits

Cuando toca pedir ayuda