Status Codes

General Information

HTTP status codes are three-digit numbers returned by the server to indicate the outcome of a request. These codes help you understand how the server processed your request and whether any issues occurred.

200 OK

Description:

The request was successful, and the server returned the requested data (if applicable).

Used For:

• A successful GET, POST, PUT, PATCH, or DELETE request where the action has been completed.

Example Response:

{
  "status": "success",
  "message": "Request processed successfully."
}

---

400 Bad Request

Description:

The server could not understand the request due to invalid syntax.

Used For:

• The client sends data that is malformed or missing required parameters.

• JSON syntax errors or invalid data formats.

Example Response:

{
  "status": "error",
  "message": "The request is malformed. Please check your input."
}

---

401 Unauthorized

Description:

The request lacks valid authentication credentials.

Used For:

• The client needs to authenticate before accessing the resource.

• The provided credentials (e.g., API keys or tokens) are incorrect or missing.

Example Response:

{
  "status": "error",
  "message": "Authentication required. Please provide valid credentials."
}

---

403 Forbidden

Description:

The server understands the request but refuses to authorize it.

Used For:

• The client does not have permission to access the requested resource.

• Authentication might be valid, but the client does not have sufficient rights.

Example Response:

{
  "status": "error",
  "message": "You do not have permission to access this resource."
}

---

404 Not Found

Description:

The server cannot find the requested resource.

Used For:

• The client requested a non-existent endpoint or resource.

• Incorrect URL or endpoint in the request.

Example Response:

{
  "status": "error",
  "message": "The requested resource could not be found."
}

---

405 Method Not Allowed

Description:

The HTTP method used is not allowed for the requested resource.

Used For:

• The client attempts to use an unsupported HTTP method (e.g., using GET when only POST is allowed).

Example Response:

{
  "status": "error",
  "message": "The HTTP method is not allowed for the requested resource."
}

---

429 Too Many Requests

Description:

The user has sent too many requests in a given amount of time, often referred to as "rate limiting."

Used For:

• When a user exceeds the rate limit for a given API or service, preventing further requests until a certain time period has passed.

Example Response:

{
  "status": "error",
  "message": "Too many requests. Please try again later."
}

---

500 Internal Server Error

Description:

The server encountered an unexpected condition that prevented it from fulfilling the request.

Used For:

• Generic server errors that don’t fall into other categories.

• Issues with the server that require troubleshooting.

Example Response:

{
  "status": "error",
  "message": "An unexpected error occurred on the server."
}

---

502 Bad Gateway

Description:

The server received an invalid response from an upstream server while attempting to fulfill the request.

Used For:

• Proxy or gateway errors where the server depends on another server for the request.

Example Response:

{
  "status": "error",
  "message": "The server received an invalid response from an upstream server."
}

---

503 Service Unavailable

Description:

The server is currently unable to handle the request due to temporary overload or scheduled maintenance.

Used For:

• Temporary issues with the server, such as maintenance or server overload.

• This usually resolves once the server is back online or under less load.

Example Response:

{
  "status": "error",
  "message": "The service is temporarily unavailable. Please try again later."
}