Responses

Balad APIs follow standard REST principles. Each response contains information about the request’s success or failure and may include error details if something went wrong.

HTTP Status Code	Description
200	Success
400	Bad Request (Input / Business Validation)
401	Unauthorized
403	Forbidden
417	Encryption Error – ensure encryption protocols and keys are properly configured
418	Configuration Issue – contact your administrator for support
500	Internal Server Error

✅ Success (HTTP Status Code: 200)

A successful response will include a data object and errors set to null.

{
  "data": {
    "prop_1": "XXXXXXXXXXXXXXXXXXX",
    "prop_2": "XXXXXXXXXXXXXXXXXXX",
    "prop_3": "XXXXXXXXXXXXXXXXXXX"
  },
  "errors": null
}

:::

Pagination

Balad APIs support pagination for endpoints that return lists of data.
The paginated response contains metadata about the current page, page size, and whether there are more records to fetch.

Paginated Response (200)

A successful response will include a data object and errors set to null.

{
  "data": {
    "page_no": 1,
    "page_size": 10,
    "has_next": true,
    "items": [
      {"abc": "XXXXXX", "xyz": "XXXX"},
      {"abc": "XXXXXX", "xyz": "XXXX"}
    ]
  }
}

INFO

maximum value for the page_size query parameter is 50

Errors (Other HTTP Status Codes)

Balad APIs return a consistent error response structure whenever a request fails.
All error responses follow the same format:

{
  "data": null,
  "errors": {
    "code": <number>,
    "description": "<string>",
    "field": "<string> (optional)"
  }
}

Important

In case of multiple errors resulting in a 4xx response, the response will include a list of "fields" and an array of error messages as "values" for those fields, explaining the errors for each field. Here is an example for reference.

Single Error Message

Multiple Error Messages

{
  "data": null,
  "errors": {
     "code": 10,
     "description": "XXXX",
     "field": "XXX"
   }
}

Responses

✅ Success (HTTP Status Code: 200)#

Pagination#

Paginated Response (200)#

Errors (Other HTTP Status Codes)#

✅ Success (HTTP Status Code: 200)

Pagination

Paginated Response (200)

Errors (Other HTTP Status Codes)