HTTP Methods & Status Codes

HTTP methods define what action the client wants to perform on a resource, while HTTP status codes indicate the result of that action.

Common HTTP Methods

1. `GET`: Fetch data from the server

Read-only, no side effects
Example: GET /users

2. `POST`: Create new data

Sends data in request body
Example: POST /users

3. `PUT`: Update an entire resource

Replaces existing data
Example: PUT /users/1

4. `PATCH`: Update part of a resource

Partial update
Example: PATCH /users/1

5. `DELETE`: Remove a resource

Example: DELETE /users/1

HTTP Status Codes

2xx Success

These codes indicate that the client's request was successfully received, understood, and accepted.

| Status Code | Constant     | Description                                                              | Recommended Usage                                                                                                          |
| ----------- | ------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| 200         | OK           | The request was successful and the response contains the requested data. | Use for successful `GET` requests and `PUT/PATCH/DELETE` requests that return a response body.                             |
| 201         | CREATED      | A new resource was successfully created.                                 | Use after a successful `POST` request that creates a resource. Include the new resource or its identifier in the response. |
| 202         | ACCEPTED     | The request has been accepted for asynchronous processing.               | Use when the request is queued or handled by a background job and processing is not yet complete.                          |
| 204         | NO_CONTENT   | The request was successful but there is no response body.                | Use for successful `DELETE` operations or updates where no data needs to be returned.                                      |

3xx Redirection

These codes indicate that the client must take additional action to complete the request.

| Status Code | Constant            | Description                                               | Recommended Usage                                                                            |
|-------------|---------------------| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| 301         | MOVED_PERMANENTLY   | The resource has been permanently moved to a new URL.     | Use when an endpoint has been permanently replaced. Clients should update stored URLs.       |
| 302         | FOUND               | The resource is temporarily available at a different URL. | Use for temporary redirects such as authentication or OAuth flows.                           |
| 304         | NOT_MODIFIED        | The resource has not changed since the last request.      | Use for caching mechanisms with `ETag` or `Last-Modified` headers to reduce bandwidth usage. |

4xx Client Errors

These codes indicate that the request contains bad syntax or cannot be fulfilled.

| Status Code | Constant               | Description                                                         | Recommended Usage                                                                   |
| ----------- | ---------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 400         | BAD_REQUEST            | The request is malformed or contains invalid parameters.            | Use for generic validation errors or malformed request payloads.                    |
| 401         | UNAUTHORIZED           | Authentication is required or the provided credentials are invalid. | Use when access tokens are missing, expired, or invalid.                            |
| 403         | FORBIDDEN              | The client is authenticated but lacks sufficient permissions.       | Use for authorization failures (e.g., RBAC or ownership checks).                    |
| 404         | NOT_FOUND              | The requested resource does not exist.                              | Use when a resource ID, endpoint, or entity cannot be found.                        |
| 409         | CONFLICT               | The request conflicts with the current state of the resource.       | Use for duplicate resources (e.g., email already exists) or state conflicts.        |
| 422         | UNPROCESSABLE_ENTITY   | The request is valid but fails domain-specific validation rules.    | Use for semantic validation errors (e.g., weak password, invalid state transition). |
| 429         | TOO_MANY_REQUESTS      | Too many requests have been sent in a given time window.            | Use when rate limits are exceeded. Include retry headers when possible.             |

5xx Server Errors

These codes indicate the server failed to fulfill an apparently valid request.

| Status Code | Constant                | Description                                                | Recommended Usage                                                |
| ----------- | ----------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- |
| 500         | INTERNAL_SERVER_ERROR   | An unexpected server error occurred.                       | Use as a fallback for unhandled exceptions or unknown failures.  |
| 501         | NOT_IMPLEMENTED         | The requested functionality is not supported.              | Use for unimplemented endpoints or feature placeholders.         |
| 502         | BAD_GATEWAY             | An invalid response was received from an upstream service. | Use when a dependent service returns an invalid response.        |
| 503         | SERVICE_UNAVAILABLE     | The service is temporarily unavailable.                    | Use during maintenance windows or when the system is overloaded. |
| 504         | GATEWAY_TIMEOUT         | An upstream service failed to respond in time.             | Use when timeouts occur while waiting for dependent services.    |

export const STATUS_CODES = {
  // 2xx Success
  OK: 200,
  CREATED: 201,
  ACCEPTED: 202,
  NO_CONTENT: 204,
 
  // 3xx Redirection
  MOVED_PERMANENTLY: 301,
  FOUND: 302,
  NOT_MODIFIED: 304,
 
  // 4xx Client Errors
  BAD_REQUEST: 400,
  UNAUTHORIZED: 401,
  FORBIDDEN: 403,
  NOT_FOUND: 404,
  CONFLICT: 409,
  UNPROCESSABLE_ENTITY: 422,
  TOO_MANY_REQUESTS: 429,
 
  // 5xx Server Errors
  INTERNAL_SERVER_ERROR: 500,
  NOT_IMPLEMENTED: 501,
  BAD_GATEWAY: 502,
  SERVICE_UNAVAILABLE: 503,
  GATEWAY_TIMEOUT: 504
} as const;
 
export type StatusCode = (typeof STATUS_CODES)[keyof typeof STATUS_CODES];