Skip to content

error-codes.md

Latest commit

 

History

History
122 lines (99 loc) · 6.42 KB

error-codes.md

File metadata and controls

122 lines (99 loc) · 6.42 KB
Raw

API error codes

Every API error returns JSON with a stable code and a short error message:

{ "code": "LMS-ADM-007", "error": "update failed" }

When reporting issues, quote the code (e.g. LMS-ADM-007) — it maps directly to the failing handler and likely root cause.

UIs append the code in brackets: update failed [LMS-ADM-007].

Auth & session (LMS-AUTH-*)

Code HTTP Message Likely cause
LMS-AUTH-001 401 missing token Request to protected route without Authorization: Bearer header
LMS-AUTH-002 401 invalid token Expired, malformed, or wrong-signing-key JWT
LMS-AUTH-003 403 forbidden Valid token but role cannot access this route
LMS-AUTH-004 429 rate limit exceeded Too many login attempts from this IP
LMS-AUTH-005 400 invalid school school_id missing or not a valid UUID
LMS-AUTH-006 401 invalid credentials Wrong username/PIN or password
LMS-AUTH-007 423 account locked Five failed logins — wait or reset via admin
LMS-AUTH-008 401 invalid refresh token Refresh token expired or revoked
LMS-AUTH-009 401 unauthorized Generic auth failure on protected route
LMS-AUTH-010 400 invalid payload Malformed JSON on auth endpoints
LMS-AUTH-011 400 school, username and 6-digit pin required Pupil login body incomplete
LMS-AUTH-012 400 school, username and password required Staff login body incomplete

Schools (LMS-SCH-*)

Code HTTP Message Likely cause
LMS-SCH-001 500 failed to load schools DB unreachable, migrations not run, or schools table empty

Practice / session (LMS-SES-*)

Code HTTP Message Likely cause
LMS-SES-001 400 invalid payload Bad JSON or missing fields on session endpoints
LMS-SES-002 404 question not found Question ID not in current session queue
LMS-SES-003 500 failed to process answer Adaptive engine or DB error saving attempt
LMS-SES-004 500 failed to generate queue Redis/DB failure building practice queue
LMS-SES-005 500 query failed DB error loading session state
LMS-SES-006 404 not found Session or resource ID does not exist

Teacher (LMS-TCH-*)

Code HTTP Message Likely cause
LMS-TCH-001 500 query failed DB error on teacher dashboard queries
LMS-TCH-002 404 pupil not found Pupil ID invalid or not in teacher's school
LMS-TCH-003 400 invalid payload Bad assign/override request body
LMS-TCH-004 500 assign failed DB error assigning work to pupil
LMS-TCH-005 404 marking not found Marking record ID not found
LMS-TCH-006 500 update failed DB error saving marking feedback
LMS-TCH-007 403 headteacher only SENCO/teacher tried a head-only action

School admin (LMS-ADM-*)

Code HTTP Message Likely cause
LMS-ADM-001 401 unauthorized Not logged in as IT admin / headteacher
LMS-ADM-002 400 invalid id UUID path param malformed
LMS-ADM-003 400 invalid payload Malformed JSON on admin create/update
LMS-ADM-004 500 query failed DB error listing users/classrooms
LMS-ADM-005 404 user not found User or classroom ID not in school
LMS-ADM-006 409 update failed Generic conflict on admin update
LMS-ADM-007 500 update failed DB error on user/classroom update (check server logs)
LMS-ADM-008 500 delete failed DB error deleting user/classroom
LMS-ADM-009 400 invalid role Role not in allowed set
LMS-ADM-010 400 pin required for pupils Creating pupil without PIN
LMS-ADM-011 400 password required for staff Creating staff without password
LMS-ADM-012 500 hash failed bcrypt error hashing PIN/password
LMS-ADM-013 409 username already exists Duplicate username in school
LMS-ADM-014 400 pin only for pupils PIN set on staff account
LMS-ADM-015 400 password not for pupils Password set on pupil account
LMS-ADM-016 400 name required Classroom name missing
LMS-ADM-017 400 teacher not found teacher_id does not exist
LMS-ADM-018 409 classroom already exists Duplicate classroom name in school
LMS-ADM-019 409 classroom has pupils — reassign them first Delete blocked while pupils assigned
LMS-ADM-020 400 CSV file required (field: file) Bulk import missing file upload
LMS-ADM-021 400 invalid CSV CSV parse/validation failure

Platform admin / SaaS (LMS-PLT-*)

Code HTTP Message Likely cause
LMS-PLT-001 400 invalid payload Malformed platform API JSON
LMS-PLT-002 401 invalid credentials Wrong platform admin username/password
LMS-PLT-003 500 token error JWT signing failure after platform login
LMS-PLT-004 500 query failed DB error on platform school/admin queries
LMS-PLT-005 409 school slug or urn already exists Duplicate school on create
LMS-PLT-006 400 invalid school id School UUID malformed
LMS-PLT-007 400 role must be it_admin or headteacher Invalid role on school admin create
LMS-PLT-008 409 username already exists for this school Duplicate school-level admin username

Interventions / SENCO (LMS-SNC-*)

Code HTTP Message Likely cause
LMS-SNC-001 500 query failed DB error loading intervention groups
LMS-SNC-002 409 group exists Duplicate intervention group name
LMS-SNC-003 500 update failed DB error updating intervention group

Assessments & MTC (LMS-ASM-*, LMS-MTC-*)

Code HTTP Message Likely cause
LMS-ASM-001 500 query failed DB error listing assessments
LMS-ASM-002 404 assessment not found Assessment ID invalid
LMS-ASM-003 500 failed to start assessment DB error creating assessment session
LMS-MTC-001 500 failed to save DB error saving MTC attempt
LMS-MTC-002 500 query failed DB error loading MTC results

Debugging workflow

  1. User copies the code from the UI or network tab (e.g. LMS-ADM-007).
  2. Look up the row in this table for HTTP status and likely cause.
  3. On the server, search logs for api error with that code — the underlying DB/driver error is logged server-side only (not exposed to clients).

Source of truth: backend/internal/apperrors/apperrors.go.