Error Handling
The API uses standard HTTP status codes and returns consistent JSON error bodies for all failure cases.HTTP status codes
Error response body
All error responses return a JSON body withsuccess: false. The structure varies by error type.
Validation error (422)
errors object maps field names to an array of human-readable messages.
Authentication error (401)
Not found (404)
Generic server error (500)
Handling errors in code
Common mistakes
Missing X-Tenant header
Missing X-Tenant header
Returns
401 or 404 depending on the endpoint. Always include X-Tenant on resource endpoints.File already in use
File already in use
When creating a certificate, the
file_uuid must reference a file that has not yet been attached to another certificate. Once a file is used, it cannot be reused.Wrong UUID format
Wrong UUID format
All UUID fields must be in standard v4 format:
550e8400-e29b-41d4-a716-446655440000. Passing an integer where a UUID is expected returns 422.Referencing entities from another tenant
Referencing entities from another tenant
If you pass a
course_uuid or student_uuid that belongs to a different tenant, the API returns 422 with "The selected ... is invalid." — the entity lookup is always tenant-scoped.