Erros

Toda resposta de erro é JSON no formato abaixo. A API não devolve texto para mostrar a pessoas: use o code (estável) para decidir o que fazer e traduza no seu sistema.

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

Campo	Quando vem	Significado
code	sempre	Código estável do erro (tabela abaixo).
fields	em VALIDATION_FAILED e CONFLICT por campo	Mapa campo → código do problema (required, invalid, too_short, too_long, out_of_range, taken, weak, reused, too_soon, wrong_password, locked).
retryAfterSeg	em RATE_LIMITED	Segundos até poder tentar de novo (o mesmo valor vai no cabeçalho Retry-After).
excecoes, falhas	em erros específicos de presença	Detalhes do pedido; veja o modelo ErroApi.
requestId	pode vir	Identificador para citar ao falar com o suporte.

Status HTTP e códigos

Status	code	O que fazer
400	VALIDATION_FAILED	Corpo, parâmetro ou consulta inválidos; fields aponta onde. Corrija e envie de novo.
401	UNAUTHENTICATED	Token ausente, vencido ou inválido. Renove ou entre de novo.
403	FORBIDDEN	A conta não tem permissão neste escopo. Em rotas com escopo (turma, disciplina, instituição), um identificador que não existe também resulta em 403. Não adianta repetir.
404	NOT_FOUND	O recurso não existe.
409	CONFLICT	Conflito com o estado atual: por exemplo fields: { "sigla": "taken" } ao criar disciplina com sigla já usada. Também no aplicar parcial sem o hashConteudo correto.
413	PAYLOAD_TOO_LARGE	Corpo maior que o limite (100 KB). Divida em partes.
422	UNPROCESSABLE	Reservado para pedidos válidos que não podem ser processados; é raro nas rotas atuais.
429	RATE_LIMITED	Muitas chamadas. Espere retryAfterSeg e tente de novo.
500	INTERNAL	Falha do servidor. Tente de novo depois, com espera crescente.

Há ainda códigos de regras de negócio (por exemplo ALREADY_CONFIRMED, FEEDBACK_CLOSED, LAST_ADMIN, LAST_CURATOR); todos estão listados no modelo ErroApi.

Quais erros repetir

Situação	Repetir?
429, 500, falha de rede	Sim, com espera (respeite Retry-After; sem ele, comece em 1 s e dobre até 60 s).
401	Uma vez, depois de renovar o token.
400, 403, 404, 409, 413, 422	Não: o resultado será o mesmo até o pedido ou o estado mudar.

Operações de importação (.../importacoes/...) são idempotentes: repetir o mesmo arquivo não duplica nada. Já POST de criação unitária (por exemplo POST /turmas/{turmaId}/atividades) não é idempotente: repetir cria outra atividade. Veja as jornadas.