Core concepts

Response envelope

Every response is a JSON envelope with a predictable shape, plus one simple rule every client should follow.

The envelope

Every response is a JSON object with these keys:

{
  "success": true,
  "success_message": "Resource has been updated successfully.",
  "error_struct": null,
  "request_id": "…",
  "action": "updated",
  "data": null
}

success - normally a boolean. Some legacy endpoints returned a string message here; the server normalizes that into success: true plus success_message.
action - on writes: updated (POST), added (PUT), deleted (DELETE).
data - the result payload; present even when an endpoint only returns a message.

Error shape

Validation and early failures return an error object:

{
  "success": false,
  "request_id": "…",
  "error": {
    "code": 40001,
    "message": "Missing required parameter: action",
    "meta": {}
  }
}

The one rule for clients

Watch out

Treat a response as successful only when success === true. Do not rely on the HTTP status alone - some legacy endpoints return 200 with success: false. Read the error message from error.message, error_struct, or a legacy error string, in that order.

In practice, a small helper covers every shape:

function isOk(payload) { return payload && payload.success === true; }
function errorMessage(payload) {
  if (!payload) return "Empty response";
  if (payload.error && payload.error.message) return payload.error.message;
  if (payload.error_struct && payload.error_struct.message) return payload.error_struct.message;
  if (typeof payload.error === "string") return payload.error;
  return "Unknown error";
}