Errores

Toda respuesta de error es JSON con el formato de abajo. La API no devuelve texto para mostrar a las personas: use el code (estable) para decidir qué hacer y tradúzcalo en su sistema.

{
  "code": "VALIDATION_FAILED",
  "fields": { "email": "invalid" }
}

Campo	Cuándo viene	Significado
code	siempre	Código estable del error (tabla de abajo).
fields	en VALIDATION_FAILED y CONFLICT por campo	Mapa campo → código del problema (required, invalid, too_short, too_long, out_of_range, taken, weak, reused, too_soon, wrong_password, locked).
retryAfterSeg	en RATE_LIMITED	Segundos hasta poder reintentar (el mismo valor va en la cabecera Retry-After).
excecoes, falhas	en errores específicos de asistencia	Detalles del pedido; vea el modelo ErroApi.
requestId	puede venir	Identificador para citar al hablar con soporte.

Estado HTTP y códigos

Estado	code	Qué hacer
400	VALIDATION_FAILED	Cuerpo, parámetro o consulta inválidos; fields indica dónde. Corrija y envíe de nuevo.
401	UNAUTHENTICATED	Token ausente, vencido o inválido. Renueve o inicie sesión de nuevo.
403	FORBIDDEN	La cuenta no tiene permiso en este ámbito. En rutas con ámbito (grupo, asignatura, institución), un identificador que no existe también resulta en 403. No sirve repetir.
404	NOT_FOUND	El recurso no existe.
409	CONFLICT	Conflicto con el estado actual: por ejemplo fields: { "sigla": "taken" } al crear una asignatura con sigla ya usada. También en el aplicar parcial sin el hashConteudo correcto.
413	PAYLOAD_TOO_LARGE	Cuerpo mayor que el límite (100 KB). Divídalo en partes.
422	UNPROCESSABLE	Reservado para pedidos válidos que no pueden procesarse; es raro en las rutas actuales.
429	RATE_LIMITED	Demasiadas llamadas. Espere retryAfterSeg y reintente.
500	INTERNAL	Falla del servidor. Reintente más tarde, con espera creciente.

Hay además códigos de reglas de negocio (por ejemplo ALREADY_CONFIRMED, FEEDBACK_CLOSED, LAST_ADMIN, LAST_CURATOR); todos están listados en el modelo ErroApi.

Qué errores reintentar

Situación	¿Reintentar?
429, 500, falla de red	Sí, con espera (respete Retry-After; sin él, empiece en 1 s y duplique hasta 60 s).
401	Una vez, después de renovar el token.
400, 403, 404, 409, 413, 422	No: el resultado será el mismo hasta que cambie el pedido o el estado.

Las operaciones de importación (.../importacoes/...) son idempotentes: repetir el mismo archivo no duplica nada. En cambio, el POST de creación unitaria (por ejemplo POST /turmas/{turmaId}/atividades) no es idempotente: repetir crea otra actividad. Vea los recorridos.