Content API Errors

The envelope

Every error from a route that takes a tf_content_ key has this shape:

{
  "error": {
    "code": "content_invalid_api_key",
    "message": "Invalid or missing Content Integration API key",
    "status": 401,
    "requestId": "3f0c2a9e-6b1d-4c8e-9f2a-7d5b1e0c4a11"
  }
}

Branch on error.code. message is for people and can change. requestId is the same value as the Request-Id response header; see Request ids. Some errors add fields: details on validation errors, allowedValues on an unknown sort field, requiredScope on scope errors, retryAfterSeconds on 429, currentETag on 412, limit, spent, requested, and resetsAt on a key's monthly credit limit, and the fields listed with each upload error in Error codes. A path that matches no route under /v1/content also returns this envelope, with 404 content_not_found.

The admin session routes for keys, webhooks, and the legacy export use the same envelope. So does a body refused before it reaches a route: a body over 100 KB answers 413 content_payload_too_large, and malformed JSON answers 400 content_invalid_request, both with a Request-Id. One response does not use it: the organization list, GET /v1/content/organizations, answers in TutorFlow's standard web shape, { "statusCode", "message", "error" }.

Request ids

Every response from /v1/content/**, success or error, carries a Request-Id header, and every error body repeats it as error.requestId. TutorFlow files its server logs and audit log under this id, so it is the fastest way for support to find your request.

To choose the id yourself, for example to match your own trace ids, send X-Request-Id (or Request-Id). It is kept when it is 1 to 128 characters of letters, digits, ., _, and -; otherwise TutorFlow generates a UUID. When both headers are sent, X-Request-Id wins.

GET /v1/content/credits
Authorization: Bearer tf_content_...
X-Request-Id: cms-sync-2026-09-30-000142
 
HTTP/1.1 200 OK
Request-Id: cms-sync-2026-09-30-000142

Log Request-Id next to the status and error.code of every failed call. Browser clients can read it: the Content API lists it in Access-Control-Expose-Headers.

What to do for each status

A Node.js and Python request() wrapper that implements this table is in Examples.

400 and 422

Both carry error.code: "content_invalid_request". The status tells you which check failed.

422: the request does not match its schema. A path parameter, body field, or query field has the wrong type, is missing, is out of range, or has an unknown value. error.details has one entry per field:

{
  "error": {
    "code": "content_invalid_request",
    "message": "Validation failed: classroomId must be a UUID",
    "details": [
      { "field": "classroomId", "message": "classroomId must be a UUID", "constraints": ["isUuid"] }
    ],
    "status": 422
  }
}

Id path parameters are checked the same way. Every parameter named id or ending in Id (classroomId, courseId, chapterId, lessonId, sceneId, webhookId, deliveryId, keyId, organizationId, and the resource ids) must be a hyphenated UUID. The check runs after authentication, so a bad key still gets 401 first:

GET /v1/content/classrooms/abc/courses
Authorization: Bearer tf_content_...
 
HTTP/1.1 422 Unprocessable Entity
Request-Id: 3f0c2a9e-6b1d-4c8e-9f2a-7d5b1e0c4a11

{
  "error": {
    "code": "content_invalid_request",
    "message": "classroomId must be a UUID",
    "details": [{ "field": "classroomId", "message": "must be a UUID" }],
    "status": 422,
    "requestId": "3f0c2a9e-6b1d-4c8e-9f2a-7d5b1e0c4a11"
  }
}

A value TutorFlow cannot parse anywhere else in the request, for example a malformed id inside a body that no field check covers, also answers 422 content_invalid_request, with the message "A value in the request is not in the expected format".

Examples of 422:

• An id path parameter that is not a UUID, or classroomId in a body that is not one.
• payload is not an object, or an unknown output in requestedOutputs.
• List queries: limit, take, or page below 1 or not an integer, a field outside the list's sort columns (with error.allowedValues), an order other than ASC or DESC, a search over 200 characters, or an updatedSince that is not an ISO 8601 date-time. See List pages.
• days on course stats other than 7 or 30.
• A course visibility outside PUBLIC, PRIVATE, ORGANIZATION, CLASSROOM, COURSE.
• A revision feedback over 2,000 characters, or a chapter title over 255 characters.
• Generation bodies: a test itemTypes whose length is not itemCount, a slide deck slideCount outside 5 to 20, or a themeId or textLength that is not listed.

Fields the schema does not know are dropped silently, not rejected.

An unknown sort field lists the columns that work:

{
  "error": {
    "code": "content_invalid_request",
    "message": "field must be one of: createdAt, updatedAt, title",
    "details": [{ "field": "field", "message": "field must be one of: createdAt, updatedAt, title", "constraints": ["isIn"] }],
    "allowedValues": ["createdAt", "updatedAt", "title"],
    "status": 422,
    "requestId": "3f0c2a9e-6b1d-4c8e-9f2a-7d5b1e0c4a11"
  }
}

400: the request is well formed but cannot be carried out. There is no details; read message.

Error codes

Scope errors name the missing scope:

{
  "error": {
    "code": "content_insufficient_scope",
    "message": "This API key lacks the content:generate scope",
    "requiredScope": "content:generate",
    "status": 403
  }
}

Errors after a request was accepted

Some work fails after the HTTP response:

A failed async run releases its Idempotency-Key, so a retry with the same key starts a new run. For a failed expansion job, fix the source JSON or the requested outputs, then submit it with a new Idempotency-Key; the old key returns the old job. For a build that failed with violations, change the brief or metadata before building again.

Contacting support

Send these, and never the full key: