API Response Codes & Error Handling

To guarantee frontend stability, Pragma CMS channels 100% of its API responses through a single unified formatting engine (sendJsonResponse()).

The Standard JSON Payload

Whether the request succeeds or fails, the API will always return an object with a success boolean.

Successful Response (200 OK):

JSON

{
  "success": true,
  "message": "Item updated successfully",
  "data": {
    "id": 12,
    "title": "Hello World"
  }
}

Error Response (4xx / 5xx):

JSON

{
  "success": false,
  "message": "Permission denied",
  "errors": [
    "The 'name' field is required."
  ]
}

Standard HTTP Status Codes

Pragma CMS relies heavily on proper HTTP semantics. You should configure your fetch interceptors (or Axios/Axios-like libraries) to catch these codes.

Code	Meaning	Context in Pragma CMS
`200`	OK	Request succeeded. The payload is in the `data` key.
`201`	Created	A new entity (e.g., a taxonomy term) was successfully created via `POST`.
`400`	Bad Request	Missing required URL parameters (like `action` or `type`), or invalid JSON payload.
`403`	Forbidden	Invalid CSRF token, missing session, or the user lacks the required `UserManager` permission.
`404`	Not Found	The requested resource (Entry, Media, Route) does not exist or is unpublished.
`422`	Unprocessable Entity	The JSON payload is well-formed, but semantic validation failed (e.g., missing a required database field).
`500`	Internal Server Error	A raw database crash or SQL syntax failure. Check the `logs/application.log` file for PDO tracebacks.

lightbulb

Tip for JS Developers

If you are building custom extensions within the Admin UI, you do not need to parse these codes manually. Simply use the global await apiRequest(url, options) function. It natively catches 4xx/5xx errors and triggers the standard CMS Error Popup UI.

Response Codes & Errors

The Standard JSON Payload

Standard HTTP Status Codes