Errors
The API uses plain HTTP status codes. Every error body is JSON with a detail field: a message, an object with a machine-readable code, or a list of validation errors.
Error body
The API is built on FastAPI, so errors carry a detail field. Most of the time it is a human-readable string. Some endpoints send an object instead, with a stable code you can branch on and a message for people.
{
"detail": "Course not found"
}{
"detail": {
"code": "RATE_LIMITED",
"message": "Too many login attempts. Please try again in 4 minutes.",
"retry_after": 263
}
}Codes in use include RATE_LIMITED, PAYMENT_REQUIRED, BATCH_TOO_LARGE, WEAK_PASSWORD and the MFA codes such as INVALID_CODE. Treat unknown codes like a plain message.
Status codes
| Status | Meaning | When |
|---|---|---|
400 | Bad request | The request is understood but not allowed as sent: a duplicate name, a weak password, a batch over its size cap (code BATCH_TOO_LARGE). |
401 | Unauthorized | No credentials, or they are invalid or expired. Detail: "Could not validate credentials". |
402 | Payment required | The content or feature needs a purchase or a higher plan (code PAYMENT_REQUIRED on paid content). |
403 | Forbidden | Authenticated, but not allowed: missing role or token right, or an API token on a session-only endpoint. |
404 | Not found | The resource does not exist, or is not visible to you. |
409 | Conflict | The request clashes with current state, for example a resource that already exists. |
413 | Payload too large | A non-multipart body is over the size cap: 25 MB by default, set with max_request_body_mb on self-hosted instances. File uploads have their own per-type limits. Detail: "Request body too large". |
422 | Unprocessable entity | The body, path or query failed validation. The detail is a list of field errors, below. |
429 | Too many requests | A rate limit was hit. See Rate limits for which endpoints have them. |
5xx | Server error | Something failed on the server or an upstream service. Safe to retry reads with backoff. |
Each endpoint lists the statuses it documents under Responses. Any endpoint can also return 401, 403 or 5xx.
Validation errors (422)
When a request does not match the endpoint's schema the API answers 422 before running anything. detail is a list with one entry per problem. loc says where: the first item is body, path or query, followed by the field name (and list indexes for nested values).
{
"detail": [
{
"type": "missing",
"loc": [
"body",
"name"
],
"msg": "Field required",
"input": {
"description": "An example description"
}
},
{
"type": "int_parsing",
"loc": [
"path",
"course_id"
],
"msg": "Input should be a valid integer, unable to parse string as an integer",
"input": "abc"
}
]
}HTTPValidationError · from the OpenAPI document
detailValidationError[]Optional5 child attributes
locstring | integer[]RequiredmsgstringRequiredtypestringRequiredinputanyOptionalctxContextOptionalHandling errors
With @learnhouse/sdk every failure throws a LearnHouseError carrying the status, the code and the API's detail. With plain fetch, check res.ok and read detail.
import { isLearnHouseError } from "@learnhouse/sdk";
try {
await lh.GET("/api/v1/courses/{course_uuid}", {
params: { path: { course_uuid: "course_…" } },
});
} catch (err) {
if (!isLearnHouseError(err)) throw err;
err.status; // 404
err.code; // "HTTP_ERROR", or the API's own code, e.g. "RATE_LIMITED"
err.detail; // the API's detail: string, object or validation list
}const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
if (!res.ok) {
const { detail } = await res.json().catch(() => ({}));
if (res.status === 422) {
for (const e of detail) console.error(e.loc.join("."), e.msg);
} else {
const message = typeof detail === "string" ? detail : detail?.message;
throw new Error(`${res.status}: ${message ?? res.statusText}`);
}
}Retry only what is safe: reads (GET) on network errors and 5xx, with backoff. For 429, wait for the time the API gives you (see Rate limits). Fix 4xx errors rather than retrying them.