Errors

Every error response is JSON in the format below. The API does not return text to show to people: use the stable code to decide what to do and translate it in your own system.

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

Field	When present	Meaning
code	always	Stable error code (table below).
fields	in VALIDATION_FAILED and per-field CONFLICT	Map of field → problem code (required, invalid, too_short, too_long, out_of_range, taken, weak, reused, too_soon, wrong_password, locked).
retryAfterSeg	in RATE_LIMITED	Seconds until you can try again (the same value goes in the Retry-After header).
excecoes, falhas	in specific attendance errors	Details of the request; see the ErroApi model.
requestId	may be present	Identifier to quote when talking to support.

HTTP status and codes

Status	code	What to do
400	VALIDATION_FAILED	Invalid body, parameter or query; fields points to where. Fix and send again.
401	UNAUTHENTICATED	Missing, expired or invalid token. Renew or sign in again.
403	FORBIDDEN	The account has no permission in this scope. On scoped routes (class, discipline, institution), an identifier that does not exist also results in 403. Retrying will not help.
404	NOT_FOUND	The resource does not exist.
409	CONFLICT	Conflict with the current state: for example fields: { "sigla": "taken" } when creating a discipline with an existing code. Also on a partial aplicar without the right hashConteudo.
413	PAYLOAD_TOO_LARGE	Body larger than the limit (100 KB). Split it.
422	UNPROCESSABLE	Reserved for valid requests that cannot be processed; rare on current routes.
429	RATE_LIMITED	Too many calls. Wait retryAfterSeg and try again.
500	INTERNAL	Server failure. Try again later, with growing waits.

There are also business-rule codes (for example ALREADY_CONFIRMED, FEEDBACK_CLOSED, LAST_ADMIN, LAST_CURATOR); all are listed in the ErroApi model.

Which errors to retry

Situation	Retry?
429, 500, network failure	Yes, with a wait (respect Retry-After; without it, start at 1 s and double up to 60 s).
401	Once, after renewing the token.
400, 403, 404, 409, 413, 422	No: the result will be the same until the request or the state changes.

Import operations (.../importacoes/...) are idempotent: repeating the same file duplicates nothing. A single-create POST (for example POST /turmas/{turmaId}/atividades), on the other hand, is not idempotent: repeating it creates another activity. See the journeys.