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 as a string404
{
  "detail": "Course not found"
}
detail as an object429
{
  "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

StatusMeaningWhen
400Bad requestThe request is understood but not allowed as sent: a duplicate name, a weak password, a batch over its size cap (code BATCH_TOO_LARGE).
401UnauthorizedNo credentials, or they are invalid or expired. Detail: "Could not validate credentials".
402Payment requiredThe content or feature needs a purchase or a higher plan (code PAYMENT_REQUIRED on paid content).
403ForbiddenAuthenticated, but not allowed: missing role or token right, or an API token on a session-only endpoint.
404Not foundThe resource does not exist, or is not visible to you.
409ConflictThe request clashes with current state, for example a resource that already exists.
413Payload too largeA 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".
422Unprocessable entityThe body, path or query failed validation. The detail is a list of field errors, below.
429Too many requestsA rate limit was hit. See Rate limits for which endpoints have them.
5xxServer errorSomething 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).

422 responseJSON
{
  "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[]Optional
5 child attributes
locstring | integer[]Required
msgstringRequired
typestringRequired
inputanyOptional
ctxContextOptional

Handling 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.

Handle errors
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
}

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.