Planifica API Error Codes

The same session id is used by more than one session in the request. Session IDs must be unique.

Two or more sessions share the same parentId but have different duration values. All sessions in a group must have the same length.

Two locked sessions are pinned to overlapping times and would require the same instructor at once.

After processing the request, no sessions remained to schedule — check your schemas/sessions data.

Something in the request (an instructor's available_days, a grade's working_hours, or a capacity/affinity/cardinality config day) references a day that isn't one of the school's configured working_days.

The request contains no classrooms at all. At least one is required.

The request contains no instructors at all. At least one is required.

A subject is used by one or more sessions, but no instructor lists that subject as something they can teach.

An instructor isn't assigned to any grade, so they can never be matched to a session.

A session has no classroom that matches its subject's room requirements. The session can still be scheduled without a fixed room, but you should add a suitable classroom.

A session's grade/subject combination has zero instructors that can teach it (after matching availability and grade assignment).

A session has matching instructors, but no time slot fits its duration alongside grade hours and other constraints.

Catch-all: a session cannot be placed anywhere that satisfies all of its requirements simultaneously (instructor, room, time, ordering, etc.).

A grade has a session whose duration exceeds the longest continuous block of available time in that grade's working hours. Lengthening or rearranging working hours is required.

The total hours of sessions that require a specific specialized room exceed the total time slots available for that room across the whole week.

A locked session assigns more hours to an instructor than they have available — either overall, or specifically within one grade.

The hours required for a (grade, subject) pair exceed the combined available capacity of instructors who can teach it.

The hours required for a subject, summed across all grades, exceed the total capacity of every instructor who can teach it.

A grade/group's total scheduled hours exceed the maximum hours available in that grade's school week.

The total teaching time needed across the whole request exceeds what all instructors combined can provide.

A locked session (with day, start, and institutor all set) falls outside that instructor's declared availability.

A locked session's start time — or its full duration — falls outside the grade's configured working_hours.

Two locked sessions belonging to the same grade/group can't both be scheduled without overlapping — their fixed times are mutually incompatible.

Two or more locked sessions require the same specialized classroom at the same time slot.

A combination of locked sessions and capacity/cardinality config windows can't be satisfied — e.g. sessions locked into a time window exceed that window's hour or count limit.

The follows constraints for a grade form a circular dependency (A follows B, B follows A, directly or transitively). Remove or rework one of the constraints.

A distance_between entry is malformed — missing both gap bounds, a negative gap, min_gap_slots > max_gap_slots, or its subject/session targets don't resolve to any session. (A small subset of these same checks are instead caught earlier as 422 schema errors.)

A distance_between constraint can't be satisfied given the other constraints in the request — e.g. no placement keeps the required minimum/maximum gap between the referenced sessions.

A cardinality_configs entry is malformed. Covers many distinct sub-cases: missing/invalid subject, cardinality <= 0, missing/invalid day or time window fields, a window that doesn't align to any timetable slot, or a duplicate window for the same subject. The message field always spells out which sub-case applies.