HTTP Method & Status Code Standardization

Standardized HTTP Methods

1. GET

• Use Case:
  • Retrieve data from the server.
  • Used for fetching information such as invoices, payments, user details, etc.
  • Should not alter any data on the server (read-only).

2. POST

• Use Case:
  • Create new resources (e.g., creating a new invoice, user, or payment).
  • Typically used for actions where new data is sent to the server and a new entity is created.

3. PUT

• Use Case:
  • Update or replace an existing resource.
  • Use when modifying details of an existing resource (e.g., updating invoice information, modifying user details).
  • Should be idempotent, meaning the result of a successful request is the same regardless of how many times it is repeated.

4. DELETE

• Use Case:
  • Remove a resource from the server (e.g., deleting an invoice, user, or payment record).
  • After successful deletion, the resource should no longer exist.

---

Standardized HTTP Status Code Guidelines

1. Successful Responses (2xx)

200 OK

• Use Case:
  • General success for GET, POST, PUT, DELETE methods.
  • Response includes data or confirmation of action.
  • Use this status code when the action is successful & some data/message needs to be returned.

201 Created

• Use Case:
  • Resource creation is successful (e.g., a new invoice or payment record is created).
  • Typically returned after a POST request.

202 Accepted

• Use Case:
  • Request is received but not yet fully processed (e.g., async operations like invoice generation or background processing).
  • Useful for long-running processes.

204 No Content

• Use Case:
  • Successful request but no content to return (e.g., DELETE operations or when a resource is successfully updated but no data is needed in the response).
  • Appropriate for actions where no additional data is necessary.

2. Client Errors (4xx)

400 Bad Request

• Use Case:
  • General client error (e.g., malformed syntax, invalid input, or missing required fields).
  • Useful for input validation errors like missing or incorrectly formatted invoice data.

401 Unauthorized

• Use Case:
  • Authentication is required but has failed or not been provided.
  • Typically returned when the user's token is expired, invalid, or missing.

403 Forbidden

• Use Case:
  • The user is authenticated but does not have the necessary permissions to access the resource.
  • Example: A user tries to access an invoice that they do not own or have no rights to view.

404 Not Found

• Use Case:
  • The requested resource was not found (e.g., endpoint).
  • Use this when a resource doesn't exist or isn't available.
  • Backend APIs should not return this status code from an API.

409 Conflict

• Use Case:
  • A conflict occurred, such as trying to update a resource that has been modified elsewhere (e.g., submitting an invoice that already exists or conflicts with the system’s state).
  • Use this when there is a resource versioning conflict or when data inconsistency prevents the action.

3. Server Errors (5xx)

500 Internal Server Error

• Use Case:
  • A generic error indicating something went wrong on the server.
  • Use this for unexpected errors, such as database issues, server crashes, or uncaught exceptions.

502 Bad Gateway

• Use Case:
  • The server acting as a gateway or proxy received an invalid response from an upstream server.
  • Example: A third-party service (e.g., payment gateway) failure.
  • This status code is returned by nginx or other web servers itself. Backend developers should not use it.

503 Service Unavailable

• Use Case:
  • The server is not available to handle the request, often due to maintenance or overload.
  • This is useful during planned downtime or when your system is under heavy load.
  • This status code is returned by nginx or other web servers itself. Backend developers should not use it.

504 Gateway Timeout

• Use Case:
  • The server did not receive a timely response from an upstream server.
  • Example: A request to an external service (e.g., payment processor) timed out.
  • This status code is returned by nginx or other web servers itself. Backend developers should not use it.

Best Practices:

• Clear Messaging: Provide clear and actionable error messages for all client errors (4xx) and server errors (5xx) to help frontend developers and users understand the issue.
• Consistent Use: Stick to the outlined status codes in all API interactions to ensure predictable behavior across the system.
• Logging and Monitoring: Always log and monitor server errors (5xx) to track issues and identify the root causes.