Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Pragyat-Nikunj/VidTube/llms.txt

Use this file to discover all available pages before exploring further.

Every response from the VidTube API — whether successful or not — follows a consistent JSON structure. This makes it straightforward to check outcomes programmatically: inspect the success field, read the message for a human-readable description, and act on the statusCode. Understanding this contract helps you write client code that handles both happy paths and failures without guessing at response shapes.

​
Success response format

Successful responses use the ApiResponse class. The success field is true whenever statusCode is less than 400. 
{
  "statusCode": 200,
  "data": {
    "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "username": "johndoe",
    "email": "john@example.com"
  },
  "message": "User fetched successfully",
  "success": true
}
FieldTypeDescription
statusCodenumberHTTP status code of the response.
dataanyThe response payload. Shape varies by endpoint.
messagestringHuman-readable description of the outcome. Defaults to "Success".
successbooleantrue when statusCode < 400, false otherwise.
For endpoints that create a resource (e.g., registering a user or publishing a video), statusCode is 201 and data contains the newly created object.

​
Error response format

Error responses use the ApiError class. The success field is always false. In development (NODE_ENV !== "production"), the response also includes a stack field with the full Node.js stack trace to help with debugging. 
{
  "statusCode": 401,
  "data": null,
  "message": "Invalid access token",
  "success": false,
  "errors": []
}
In development, the same error also includes: 
{
  "statusCode": 401,
  "data": null,
  "message": "Invalid access token",
  "success": false,
  "errors": [],
  "stack": "ApiError: Invalid access token\n    at verifyJWT (/src/middlewares/auth.middleware.js:18:11)\n    ..."
}
FieldTypeDescription
statusCodenumberHTTP status code of the error.
datanullAlways null for errors.
messagestringHuman-readable error description.
successbooleanAlways false for errors.
errorsarrayAdditional error details, such as validation failures. Empty array if not applicable.
stackstringStack trace. Only present when NODE_ENV is not "production".
Stack traces are included in error responses only when the server is running with NODE_ENV set to anything other than "production". In production, the stack field is omitted entirely, so you do not expose internal file paths or implementation details to callers.

​
HTTP status codes

StatusMeaningCommon causes in VidTube
200 OKRequest succeeded.Fetching a user, video, comments, or any read operation.
201 CreatedResource was created.Registering a user, publishing a video, creating a playlist or tweet.
400 Bad RequestThe request is malformed or missing required fields.Missing required body fields, invalid MongoDB ObjectId format.
401 UnauthorizedAuthentication failed or no credentials provided.No token, malformed token, expired access token, wrong password, invalid refresh token.
404 Not FoundThe requested resource does not exist.User not found, video not found, channel not found.
500 Internal Server ErrorAn unexpected error occurred on the server.Cloudinary upload failed, JWT token generation failed, unhandled exception.

​
Tips for callers

Always check the success field first. Even if the HTTP status code is in the 2xx range, reading success confirms the API considers the operation successful. Read message for context. The message field gives you a plain-language explanation of what happened, including for errors. This is more reliable than parsing the HTTP status code alone because VidTube may return the same status code for multiple distinct error conditions. Handle 401 with token rotation in mind. When you receive a 401 on a protected endpoint after a period of inactivity, your access token has likely expired. Call POST /users/refresh-Token with your refresh token to obtain a new access token, then retry the original request. If the refresh also returns 401, the refresh token has expired and the user must log in again. Expect an empty errors array on most errors. The errors array is populated for validation scenarios but is an empty array ([]) for most error types. Do not rely on it being non-empty to detect an error — use success: false instead. Do not display stack to end users. The stack trace is a development aid. Strip it from any error output shown in a production UI.

Build docs developers (and LLMs) love

Get started for freeTalk to us