Skip to main content

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 with success: false. The structure varies by error type.

Validation error (422)

The 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

Returns 401 or 404 depending on the endpoint. Always include X-Tenant on resource endpoints.
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.
All UUID fields must be in standard v4 format: 550e8400-e29b-41d4-a716-446655440000. Passing an integer where a UUID is expected returns 422.
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.