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 a set of sessions needs exceed what their eligible instructors can share across them. Two checks raise it:

• Per subject — the hours for one subject, summed across all grades, exceed the total capacity of every instructor who can teach it. subject is set; details carries required_hours and available_hours.
• Shared instructors — instructors who teach several subjects or grades cannot split their available slots and weekly budgets to cover every eligible session, even though each subject fits on its own. details.constraint_type is shared_instructor_capacity; session_ids lists the affected sessions, and details adds deficit_hours, instructor_ids, instructor_names, grades, and subjects. grade and subject are set only when a single grade or subject is affected — otherwise read details.grades and details.subjects.

Add availability or capacity to the listed instructors, assign more instructors to the listed subjects, or reduce the sessions' hours.

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.

The sessions of one grade, subject, and group cannot fit the capacity_configs hour limits or cardinality_configs session-count limits of their time windows, given the times those sessions are allowed to start (including locked sessions). grade, subject, group, and session_ids are set. Three checks raise it:

• One window overflows — the hours or sessions that unavoidably overlap a single window exceed its limit. details carries forced_sessions, required_hours, capacity_hours, cardinality_limit, window_start_slot, and window_end_slot.
• Combined hour limits — no placement fits all sessions across the windows' hour budgets. details.constraint_type is combined_window_capacity; details adds required_hours, available_hours, deficit_hours, and a windows array of start_slot, end_slot, and capacity_hours.
• Combined session limits — no placement fits all sessions across the windows' session-count budgets. details carries total_sessions, windows, capacity_outside_windows, and total_available.

Raise the window limits, widen the windows, or free up allowed start times outside them.

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.

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.