Status Codes

Explanation of HTTP status codes used, when to use them, etc.

GENERAL

• 200 OK: Successful GET/PUT/POST (anything successful)

• 201 Created: Resource successfully created.

• 204 No Content: Successful DELETE.

• 400 Bad Request: General error for malformed requests.

• 401 Unauthorized: Authentication error. Or Unauthenticated user

• 403 Forbidden: User is logged in, but doesn't have correct permissions

• 404 Not Found: Content / Route not found

• 402 Payment Required: User's free trial expired and they do not have a paid subscription

• 426 Upgrade Required: User has a paid account, but does not have access to the feature

• ... (continue with other codes; reorganize how you wish; add more detail)

Front End Usage (mocking responses via Storybook)

_mock.ts // src/api/_mock.ts)

export const STATUS_CODE = {
  SUCCESS: 200, // any successful CRUD operation
  BAD_REQUEST: 400, // e.g. trying to deactivate resource that is in use by another resource (e.g. note/file category), ...
  UNAUTHORIZED: 401, // aka unauthenticated (authentication/logged in check)
  FORBIDDEN: 403, // e.g. restricted permissions
  NOT_FOUND: 404, // e.g. another company's resource, a resource a user doesn't have access to, etc.
  UNPROCESSABLE_ENTITY: 422, // RecordInvalid / NotNullViolation (e.g. trying to create a record with the wrong fields, or a null field that is required)
  UPGRADE_REQUIRED: 426, // e.g. trying to access a feature that is not available in the current plan
  PAYMENT_REQUIRED: 402, // e.g. company trial has expired
  INTERNAL_SERVER_ERROR: 500, // "Something went wrong."
  // not actually used in BE, but here as "catch-all" for not-yet-handled (or not allowed) methods
  METHOD_NOT_ALLOWED: 405, // "Method Not Allowed"
};

TABLE

Request Type	Route	Condition	Status Code	Status Text	Message / Reason
GET	/resource	Successful	200	OK	Data is successfully retrieved.
GET	/resource/:id	Record not found	404	Not Found	"Resource record not found"
GET	/resource/:id	Successful	200	OK	Data is successfully retrieved.
POST	/resource	ForbiddenError (Creation not allowed)	403	Forbidden	"You are not authorized to perform this action"
POST	/resource	Successful Creation	200	OK	Data is successfully created.
PUT	/resource/:id	ForbiddenError (Update not allowed)	403	Forbidden	"You are not authorized to perform this action"
PUT	resource/:id	Bad Request	400	Bad Request	"Cannot deactivate resource because it is in use by one or more other resources"
PUT	/resource/:id	Successful Update	200	OK	Data is successfully updated.
DELETE	/resource/:id	ForbiddenError (Deletion not allowed)	403	Forbidden	"You are not authorized to perform this action"
DELETE	/resource/:id	Bad Request	400	Bad Request	"Cannot delete resource because it is in use by one or more resources"
DELETE	/resource/:id	Successful Deletion	200	OK	Data is successfully deleted.
Any	Any	RecordInvalid	422	Unprocessable Entity	Specific model validation errors
Any	Any	NotNullViolation	422	Unprocessable Entity	Specific null violation message
Any	Any	UpgradeRequiredError	426	Upgrade Required	"Resource limit reached. Please upgrade your plan to add more"
Any	Any	PaymentRequired	402	Payment Required	"Your company trial has expired."
Any	Any	Not Authenticated	401	Unauthorized	"User not found, Please log out and log back in."
Any	Any	InternalServerError	500	Internal Server Error	"Something went wrong."

Notes:

• This table was created largely based on (1) api_controller.rb and (2) note_categories_controller.rb

• The "Any" errors (RecordNotFound, RecordInvalid, NotNullViolation, etc.) are generic error handlers that could be triggered on any type of request (GET, POST, PUT, DELETE) if the corresponding exception is raised.

• The ForbiddenError is raised when the user does not have the necessary roles to perform create, update, or delete actions.

• The condition "Successful" implies that the operation completed without triggering any of the exceptions handled in the ApiController.