API Response Documentation

This document describes the structure of standardized API responses returned from the server. The responses follow a consistent format, ensuring clarity in the status, message, data, and potential errors.

ServerResponse JSON Format

Each response includes the following fields:

• status: The HTTP status of the response (e.g., OK, BAD_REQUEST, UNPROCESSABLE_ENTITY).
• statusCode: The corresponding HTTP status code (e.g., 200, 400, 422).
• series: The HTTP status series (e.g., SUCCESSFUL, CLIENT_ERROR).
• code: A custom code representing the server's response status (e.g., 20, 25, 40).
• phrase: A brief phrase summarizing the HTTP status (e.g., "Successful", "Failure", "Validation error").
• message: A detailed message describing the response.
• data: The data returned with the response, typically the payload.
• error: An error object providing additional information if applicable.
• timestamp: The timestamp when the response was generated, in dd-MM-yyyy hh:mm:ss a format.

Example Responses

1. Successful Server Response

{
  "status": "OK",
  "statusCode": 200,
  "series": "SUCCESSFUL",
  "code": 20,
  "phrase": "Successful",
  "message": "Operation successful",
  "data": {
    "loanNumber": "202412345675"
  },
  "error": null,
  "timestamp": "09-11-2024 10:30:00 AM"
}

2. Ambiguous Server Response

{
  "status": "OK",
  "statusCode": 200,
  "series": "SUCCESSFUL",
  "code": 25,
  "phrase": "Ambiguous",
  "message": "The request was ambiguous",
  "data": {
    "loanNumber": "202412345675"
  },
  "error": null,
  "timestamp": "09-11-2024 10:31:00 AM"
}

3. Failure Server Response

{
  "status": "OK",
  "statusCode": 200,
  "series": "SUCCESSFUL",
  "code": 26,
  "phrase": "Failure",
  "message": "Failed to process request",
  "data": {
    "loanNumber": "202412345675"
  },
  "error": null,
  "timestamp": "09-11-2024 10:32:00 AM"
}

4. Validation Error Server Response (Basic)

{
  "status": "BAD_REQUEST",
  "statusCode": 400,
  "series": "CLIENT_ERROR",
  "code": 41,
  "phrase": "Validation error",
  "message": "Validation error occurred",
  "data": null,
  "error": null,
  "timestamp": "09-11-2024 10:33:00 AM"
}

5. Validation Error Server Response (With Custom HTTP Status)

{
  "status": "FORBIDDEN",
  "statusCode": 403,
  "series": "CLIENT_ERROR",
  "code": 41,
  "phrase": "Validation error",
  "message": "Custom validation error message",
  "data": null,
  "error": null,
  "timestamp": "09-11-2024 10:34:00 AM"
}

6. Validation Error Server Response (With ApiError)

{
  "status": "BAD_REQUEST",
  "statusCode": 400,
  "series": "CLIENT_ERROR",
  "code": 41,
  "phrase": "Validation error",
  "message": "Validation failed",
  "data": null,
  "error": {
    "tittle": "Invalid Field",
    "message": "The field 'name' is required.",
    "apiErrors": [
      {
        "field": "name",
        "rejectedValue": null,
        "message": "Field 'name' is required."
      }
    ]
  },
  "timestamp": "09-11-2024 10:35:00 AM"
}

7. Insufficient Balance Server Response

{
  "status": "PAYMENT_REQUIRED",
  "statusCode": 402,
  "series": "CLIENT_ERROR",
  "code": 42,
  "phrase": "Insufficient balance",
  "message": "Insufficient balance to complete the transaction",
  "data": null,
  "error": null,
  "timestamp": "09-11-2024 10:36:00 AM"
}

8. Unauthorizeded Server Response

{
  "status": "UNAUTHORIZED",
  "statusCode": 401,
  "series": "CLIENT_ERROR",
  "code": 43,
  "phrase": "Unauthorized",
  "message": "User is not authorised to perform this request.",
  "data": null,
  "error": null,
  "timestamp": "09-11-2024 10:36:00 AM"
}

Custom Response Code

The ServerResponseStatus enum defines custom status codes and reason phrases for the response.

Code	Phrase	HTTP Status Series
20	Successful	SUCCESSFUL
25	Ambiguous	SUCCESSFUL
26	Failure	SUCCESSFUL
41	Validation error	CLIENT_ERROR
42	Insufficient balance	CLIENT_ERROR
43	Unauthorized	CLIENT_ERROR
50	Server error	SERVER_ERROR

Each status code is associated with an HTTP status series (e.g., SUCCESSFUL, CLIENT_ERROR, SERVER_ERROR) and a phrase (e.g., "Successful", "Failure").

Notes

• The timestamp format used is dd-MM-yyyy hh:mm:ss a (e.g., 09-11-2024 10:30:00 AM).
• The error field may contain detailed error information, including a list of specific validation errors or other issues that occurred during processing.