API Guide
Response Format
Standard response envelope, error format, pagination, and HTTP status codes for all DCMS APIs.
All DCMS APIs return a consistent response envelope.
Success Response
{
"result": {
// Response data specific to the API
},
"exception": null,
"pagination": {
"pageNo": 1,
"pageSize": 20,
"totalRecords": 150,
"totalPages": 8
}
}Error Response
{
"result": null,
"exception": {
"errorCode": "card.blocked",
"errorMessage": "Card is blocked and cannot perform this operation",
"httpStatus": "400 BAD_REQUEST"
},
"pagination": null
}Response Fields
| Field | Type | Description |
|---|---|---|
result | Object | null | Response data on success; null on error |
exception | Object | null | Error details on failure; null on success |
exception.errorCode | String | Machine-readable error code |
exception.errorMessage | String | Human-readable description |
exception.httpStatus | String | HTTP status code and reason |
pagination | Object | null | Present for paginated list APIs |
pagination.pageNo | Number | Current page number |
pagination.pageSize | Number | Results per page |
pagination.totalRecords | Number | Total matching records |
pagination.totalPages | Number | Total pages available |
Always Check the Exception Field
Even on HTTP 200, validate that exception is null. Some business errors may return 200 with an error payload.
HTTP Status Codes
| Code | Meaning | Action |
|---|---|---|
200 | Success | Process the result field |
400 | Bad Request | Validation failure or business rule violation — do not retry |
401 | Unauthorized | Missing or invalid JWT token — re-authenticate |
403 | Forbidden | Insufficient permissions — check RBAC role |
404 | Not Found | Resource does not exist |
429 | Too Many Requests | Rate limit exceeded — back off and retry |
500 | Internal Server Error | Unexpected failure — retry with exponential backoff |