Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/floriansalvi/HEIG-VD_Ocha-api/llms.txt

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

The Ocha API communicates the outcome of every request through standard HTTP status codes. Errors originating from Mongoose validation or duplicate key constraints are normalized by the utils/errorHandler.js utility before being sent to the client. The table below summarizes all codes, followed by detailed descriptions of when each one occurs and how to respond to it.

​
Status code summary

CodeNameMeaning
200OKRequest succeeded; resource(s) returned in body
201CreatedNew resource created; resource returned in body
204No ContentResource deleted; no body returned
400Bad RequestRequest is malformed or missing required data
401UnauthorizedJWT token is missing, expired, or invalid
403ForbiddenAuthenticated, but the account lacks admin role
404Not FoundRequested resource does not exist
409ConflictUnique constraint violated (duplicate key)
422Unprocessable EntityRequest body failed Mongoose schema validation
500Internal Server ErrorUnexpected server-side error

​
200 OK

The request was processed successfully and the response body contains the requested data. When it occurs
  • GET requests that retrieve one or more resources (users, products, stores, orders, order items, order stats)
  • PATCH requests that update an existing resource
What to do Parse the response body. No action is required on the client side.

​
201 Created

A new resource was created successfully. The newly created document is returned in the response body. When it occurs
  • POST /api/v1/auth — new user account registered
  • POST /api/v1/products — new product created (admin)
  • POST /api/v1/stores — new store created (admin)
  • POST /api/v1/orders — new order placed by authenticated user
What to do Store or display the returned resource. For auth endpoints, save the JWT from the response for use in subsequent requests.

​
204 No Content

The resource was deleted successfully. The response body is empty. When it occurs
  • DELETE /api/v1/products/{productId} — product deleted (admin)
  • DELETE /api/v1/stores/{storeId} — store deleted (admin)
  • DELETE /api/v1/orders/{orderId} — order deleted
What to do Remove the deleted resource from local state. Do not attempt to parse the response body.

​
400 Bad Request

The request is malformed, missing required fields, or contains a value that cannot be understood by the server. When it occurs
  • Required body fields are absent (e.g., missing pickup date when creating an order)
  • A field value is of the wrong type before it reaches Mongoose validation
What to do Review the request body against the data model reference. Ensure all required fields are present and correctly typed.
Example 400 response
{
  "message": "Bad request",
  "error": "pickup is required"
}

​
401 Unauthorized

The request requires authentication, but no valid JWT was provided. When it occurs
  • The Authorization header is absent on a protected route
  • The JWT has expired (tokens are valid for 7 days)
  • The JWT signature is invalid
What to do Include a valid JWT in the Authorization header using the Bearer scheme. Obtain a new token via POST /api/v1/auth/login if the current one has expired.
Example authorization header
Authorization: Bearer <your_jwt_token>
JWTs expire after 7 days. Your client must handle 401 responses by redirecting the user to the login flow.

​
403 Forbidden

The request is authenticated, but the account does not have the admin role required for the endpoint. When it occurs
  • A user-role account attempts to call an admin-only route (e.g., creating or deleting a product or store, reading order statistics)
What to do Do not retry with the same credentials. Admin access must be granted at the account level. Contact the system administrator to elevate the account role if legitimate access is needed.

​
404 Not Found

The requested resource does not exist in the database. When it occurs
  • GET /api/v1/products/{productId} — no product matches the given ID
  • GET /api/v1/stores/{storeId} — no store matches the given ID
  • GET /api/v1/orders/{orderId} — no order matches the given ID, or the order belongs to a different user
What to do Verify that the ID in the request path is correct and refers to an existing document. IDs are MongoDB ObjectId strings (24 hex characters).
Example 404 response
{
  "message": "Product not found"
}

​
409 Conflict

A unique constraint was violated. The resource you are trying to create or update would duplicate a field that must be unique. When it occurs
  • Registering a user with an email or display_name that already exists (POST /api/v1/auth)
  • Creating a product with a name that already exists
  • Creating a store with a name or email that already exists
This code is returned by handleMongooseError when Mongoose reports error code 11000 (duplicate key). What to do Choose a different value for the conflicting field. The error message from the API will identify which field caused the conflict.
Example 409 response
{
  "message": "Data conflict",
  "error": "E11000 duplicate key error collection: ocha.users index: email_1 dup key: { email: \"[email protected]\" }"
}

​
422 Unprocessable Entity

The request body was received but failed Mongoose schema validation. The data is syntactically valid but semantically incorrect. When it occurs
  • A field value falls outside its allowed enum (e.g., size: "XL" instead of S, M, or L)
  • A number is below its minimum (e.g., basePriceCHF: -1)
  • A string violates a length constraint (e.g., store name shorter than 3 characters)
  • opening_hours does not contain exactly 7 entries, or an entry is not [] or a valid ["HH:MM", "HH:MM"] pair
  • location.coordinates does not contain exactly two valid numbers
This code is returned by handleMongooseError when Mongoose throws a ValidationError. What to do Read the error field in the response body for the specific validation message. Correct the offending field and resubmit.
Example 422 response
{
  "message": "Invalid data",
  "error": "Product validation failed: basePriceCHF: Path `basePriceCHF` (-1) is less than minimum allowed value (0)."
}

​
500 Internal Server Error

An unexpected error occurred on the server that was not handled by a more specific error path. When it occurs
  • A database connection failure
  • An unhandled exception in a controller
  • Any error that is not a Mongoose ValidationError or duplicate key error, caught by handleMongooseError
What to do This is a server-side issue. Check the server logs for the underlying exception. If you are consuming the API as a client, retry the request after a short delay. If the error persists, report it to the API maintainer.
Example 500 response
{
  "message": "An unexpected error occurred",
  "error": "<error detail>"
}
The error field in 500 responses may expose internal details. In a production deployment, consider suppressing this field from external-facing responses.

Build docs developers (and LLMs) love

Get started for freeTalk to us