In-App Notifications (The Bell)

Author: Josh S. Sakweli, Backend Lead Team
Last Updated:Updated: 2025-10-26
2026-09-18 Version:Version: v1.0

Base URL:URL: http://localhost:8765/api/v1 (local) — https://dev.api.nextgate.com/nexgate.co/api/v1 (staging)

Short Description

TheThis Notificationdocument Managementis APIONLY providesfor a comprehensivethe in-app notification systembell — the 🔔 icon, its red badge, and the list that allowsopens userswhen you tap it. It is not about push notifications on the lock screen, email, SMS, or chat unread badges. Those are different systems; Part 0 tells you which one you need.

v1.0 — verified end to receive,end manage,on staging on 2026-09-18: one account liked another's post, the owner's badge went from 0 to 1, and interactthe withbell notificationslist acrossshowed different"joshdoe servicesliked andyour shops.post" pointing at the right post. Every JSON sample below is a real staging response.

Short Description: Everything that happens to a user while they are not looking — a like, a new follower, an order shipped, a ticket bought — is saved as one row in their bell list. This API supportsreads creatingthat notifications,list, markingcounts unread rows for the badge, marks rows read, and deletes them. The server also sends a live notification.added event on the existing event stream so the badge moves without the app polling.

Hints:

• Every endpoint needs Authorization: Bearer <accessToken>. A user only ever sees their own rows — there is no way to read someone else's bell.
• Pages start at 1, not 0. page=0 returns 400 "Page index must not be less than zero".
• The row's title is the whole sentence ("joshdoe liked your post"). message is an optional second line and is often an empty string. Never show an empty grey line.
• createdAt and readAt carry no timezone. They are UTC. Append Z before parsing, or "2 minutes ago" will be off by your offset.
• Tapping a row opens targetType + targetId. If your app does not know the targetType, stay on the bell list. That rule is what lets the backend add new notification types without breaking old app versions (Part 3).
• Ignore unknown keys inside data. It carries values the server used to build the sentence; some of them asare read,internal.
filtering

Part 0 — Is this the right document?

The same event can reach a user through several of these at once. A like creates one bell row and, once push is live, one push. They are independent: reading the bell row does not clear the push, and vice versa.

Part 1 — How the bell works

  somebody likes your post
            │
            ▼
  backend saves one row in YOUR bell list  ──────►  row: isRead=false
            │
            ▼
  backend sends on /api/v1/events:
     event: notification.added
     data:  {"type":"SOC_POST_LIKED","unreadCount":4}
            │
            ▼
  app sets the badge to 4  (no request needed)
  if the bell list is open → refetch page 1

What the app does, screen by variousscreen

Hints

Things the server does NOT tell you live

• AuthenticationMarking Required:read sends no event. All endpoints under /notifications require Bearer token authentication exceptIf the same user has the app open on a phone and a tablet and reads on one, the other keeps its old badge until it next calls /notifications/in-unread-count. Call it whenever the app endpointreturns to the foreground.
• Pagination:Deleting sends no event Listeither. endpointsUpdate supportyour paginationlist locally.

The live event

The bell rides the same stream the chat uses — GET /api/v1/events (see chatbox-api-doc.md → "SSE stream" for connecting, reconnecting with default page=1Last-Event-ID, and size=20why

{
  time

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:23:04.211589898",
  "data": {
    // Actual response data goes here }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:23:06.226159977",
  "data": "Error description"
}

Standard Response Fields

Responses may also carry action and context (always null here) — ignore them.

The page object

Endpoints 1, 2, 5 and 6 return this inside data:

{
  "notifications": [ /* notification objects, newest first */ ],
  "currentPage": 1,
  "pageSize": 20,
  "totalElements": 1,
  "totalPages": 1,
  "hasNext": false,
  "hasPrevious": false,
  "isFirst": true,
  "isLast": true
}

New rows can arrive while the user scrolls, which shifts every later page by one. If you see the same id twice, keep one.

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

• GET - GET - Green (Safe, read-only operations)
• POSTPUT - Blue (Create new resources)
• PUT - Yellow (Update/replace entire resource)Update)
• DELETE - DELETE - Red (Remove resources)

Endpoints

#	Method	Path	Use it for
1	GET	/notifications/me	The bell list
2	GET	/notifications/unread	Only unread rows
3	GET	/notifications/unread-count	The badge
4	GET	/notifications/summary	Total / unread / read counts
5	GET	/notifications/service/{serviceType}	A filter tab
6	GET	/notifications/shop/{shopId}	A shop owner's shop notifications
7	GET	/notifications/{notificationId}	One row
8	PUT	/notifications/{notificationId}/read	Mark one read
9	PUT	/notifications/read	Mark several read
10	PUT	/notifications/read-all	Mark everything read
11	DELETE	/notifications/{notificationId}	Delete one
12	DELETE	/notifications/batch	Delete several
13	DELETE	/notifications/read	Delete every read row

---

1. GetList My Notifications

Purpose:Purpose: RetrieveThe allbell notificationslist — every row for the authenticatedsigned-in useruser, withread paginationand supportunread, newest first.

Endpoint:Endpoint: GET {base_url}/notifications/me

Access Level:Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication:Authentication: Bearer Token

Request Headers

Query Parameters

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notifications retrieved successfully",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:23:04.211589898",
  "data": {
    "notifications": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000"6e902bb6-9b38-49c6-825e-22b951f39584",
        "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc"02db7d92-b426-47b2-9171-cf15339c1376",
        "shopId": "456e7890-e89b-12d3-a456-426614174001",null,
        "serviceId": "ORD-2024-001"2b5f3f0c-6d6e-4c4a-a10a-34b622a1fc68",
        "serviceType": "ORDER"SOCIAL",
        "targetType": "POST",
        "targetId": "2b5f3f0c-6d6e-4c4a-a10a-34b622a1fc68",
        "title": "Orderjoshdoe Confirmed"liked your post",
        "message": "Your order #ORD-2024-001 has been confirmed"",
        "type": "SUCCESS"SOC_POST_LIKED",
        "priority": "MEDIUM"LOW",
        "isRead": false,
        "data": { "orderId"actor": { "name": "ORD-2024-001"joshdoe" }, "amount": 150.00,
          "currency"postId": "USD"2b5f3f0c-6d6e-4c4a-a10a-34b622a1fc68" },
        "createdAt": "2025-10-26T09:15:30"2026-09-18T19:18:40.736493",
        "readAt": null
      }
    ],
    "currentPage": 1,
    "pageSize": 20,5,
    "totalElements": 45,1,
    "totalPages": 3,1,
    "hasNext": true,false,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": falsetrue
  }
}

Success Response Fields

Error Response JSON Sample

{
  "success": false,
  "httpStatus": "UNAUTHORIZED"BAD_REQUEST",
  "message": "TokenPage hasindex expired"must not be less than zero",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:23:06.226159977",
  "data": "TokenPage hasindex expired"must not be less than zero"
}

Standard Error Types:

• 400 BAD_REQUEST: page is 0 or negative
• 401 UNAUTHORIZED: Token missing, invalid or expired

2. GetList Unread Notifications

Purpose:Purpose: RetrieveOnly onlyrows unreadwith notificationsisRead=false, newest first — for thean authenticated"Unread" usertab.

Endpoint:Endpoint: GET {base_url}/notifications/unread

Access Level:Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication:Authentication: Bearer Token

Request Headers

Query Parameters

Success Response JSON Sample

{
  "success": true,identical "httpStatus":in "OK",shape "message":to "Notificationsendpoint retrieved1.

successfully",

"action_time":
Marking "2025-10-26T10:30:45",a "data":row {read "notifications":removes [it {from "id":this "223e4567-e89b-12d3-a456-426614174002",list, "userId":so "987fcdeb-51a2-43d7-9c4e-123456789abc",every "shopId":later null,page "serviceId":shifts "PAY-2024-050",up
"serviceType":by "PAYMENT",one. "title":If "Paymentyou Pending",mark "message":rows "Yourread paymentwhile the user scrolls this tab, refetch from
page 1 instead of asking for orderthe #ORD-2024-001next page.


Standard Error Types:


400 BAD_REQUEST: page is pending",0 "type"or negative

401 UNAUTHORIZED: "WARNING",Token "priority":missing, "HIGH",invalid "isRead":or false,expired
"data": {
          "paymentId": "PAY-2024-050",
          "amount": 150.00
        },
        "createdAt": "2025-10-26T10:15:30",
        "readAt": null
      }
    ],
    "currentPage": 1,
    "pageSize": 20,
    "totalElements": 12,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": true
  }
}

3. Get Unread Count

Purpose:Purpose: GetThe number on the total count of unread notifications for the authenticated userbadge.

Endpoint:Endpoint: GET {base_url}/notifications/unread-count

Access Level:Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication:Authentication: Bearer Token

Request Headers

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "Unread count retrieved successfully",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:23:05.489594598",
  "data": { "unreadCount": 121 }
}

Success Response Fields

Call it when the app starts and every time it returns to the foreground. While the app is open, notification.added keeps the badge current without calling this.

Standard Error Types:

• 401 UNAUTHORIZED: Token missing, invalid or expired

4. Get Notification Summary

Purpose:Purpose: GetTotal, a summary of all notifications including total, unread,unread and read counts in one call.

Endpoint:Endpoint: GET {base_url}/notifications/summary

Access Level:Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication:Authentication: Bearer Token

Request Headers

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification summary retrieved successfully",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:23:04.820411225",
  "data": { "total": 45,1, "unread": 12,1, "read": 330 }
}

Success Response Fields

Standard Error Types:

• 401 UNAUTHORIZED: Token missing, invalid or expired

5. Get NotificationsList by Shop

Purpose:Purpose: RetrieveOne notificationsfilter filteredtab by— ae.g. specificonly shopSOCIAL, or only ORDER.

Endpoint:Endpoint: GET {base_url}/notifications/shop/service/{shopId}serviceType}

Access Level:Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication:Authentication: Bearer Token

Request Headers

Path Parameters

{
  "success": true,identical "httpStatus":in "OK",
  "message": "Notifications retrieved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "notifications": [
      {
        "id": "323e4567-e89b-12d3-a456-426614174003",
        "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc",
        "shopId": "456e7890-e89b-12d3-a456-426614174001",
        "serviceId": "PROD-2024-100",
        "serviceType": "PRODUCT",
        "title": "New Product Available",
        "message": "A new product has been addedshape to yourendpoint shop",
        "type": "INFO",
        "priority": "LOW",
        "isRead": true,
        "data": {
          "productId": "PROD-2024-100",
          "productName": "Sample Product"
        },
        "createdAt": "2025-10-25T14:20:00",
        "readAt": "2025-10-25T15:30:00"
      }
    ],
    "currentPage": 1,
    "pageSize": 20,
    "totalElements": 8,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": true
  }
}

Purpose: Retrieve notifications filtered by service type1.

Endpoint:Standard Error Types:

• 400 BAD_REQUEST: page is 0 or negative
• 401 UNAUTHORIZED: Token missing, invalid or expired

6. List a Shop's Notifications

Purpose: For a shop owner — only the rows about one of their shops (new orders, low stock, reviews…).

Endpoint: GET {base_url}/notifications/service/shop/{serviceType}shopId}

Access Level:Level: 🔒 Protected (Requiresuse Beareronly Tokenfor Authentication)a shop the signed-in user owns)

Authentication:Authentication: Bearer Token

Request Headers

Path Parameters

Query Parameters

Success Response JSON Sample

{
  "success": true,identical "httpStatus":in "OK",shape "message":to "Notificationsendpoint retrieved1; successfully",every "action_time": "2025-10-26T10:30:45",
  "data": {
    "notifications": [
      {
        "id": "423e4567-e89b-12d3-a456-426614174004",
        "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc",
        "shopId": "456e7890-e89b-12d3-a456-426614174001",
        "serviceId": "ORD-2024-002",
        "serviceType": "ORDER",
        "title": "Order Shipped",
        "message": "Your order #ORD-2024-002row has beenthis shipped",shopId.

"type"
Standard Error Types:


400 BAD_REQUEST: "SUCCESS",shopId "priority"is not a UUID, or page is 0 or negative

401 UNAUTHORIZED: "MEDIUM",Token "isRead":missing, false,invalid "data":or {expired
"orderId": "ORD-2024-002",
          "trackingNumber": "TRK123456789"
        },
        "createdAt": "2025-10-26T08:45:00",
        "readAt": null
      }
    ],
    "currentPage": 1,
    "pageSize": 20,
    "totalElements": 15,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": true
  }
}

7. Get One Notification by ID

Purpose:Purpose: RetrieveFetch a single row — e.g. when the app opens from a link that carries a notification by its unique identifierid.

Endpoint:Endpoint: GET {base_url}/notifications/{notificationId}

Access Level:Level: 🔒 Protected (Requiresown Bearerrows Token Authentication)only)

Authentication:Authentication: Bearer Token

Request Headers

Path Parameters

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification retrieved successfully",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:23:04.211589898",
  "data": { "id":/* "123e4567-e89b-12d3-a456-426614174000",one "userId":notification "987fcdeb-51a2-43d7-9c4e-123456789abc",object "shopId": "456e7890-e89b-12d3-a456-426614174001",
    "serviceId": "ORD-2024-001",
    "serviceType": "ORDER",
    "title": "Order Confirmed",
    "message": "Your order #ORD-2024-001 has been confirmed",
    "type": "SUCCESS",
    "priority": "MEDIUM",
    "isRead": false,
    "data": {
      "orderId": "ORD-2024-001",
      "amount": 150.00,
      "currency": "USD"
    },
    "createdAt": "2025-10-26T09:15:30",
    "readAt": null*/ }
}

Error Response JSON Sample

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:23:06.905963899",
  "data": "Notification not found or access denied"
}

Standard Error Types:

• 401 UNAUTHORIZED: Token missing, invalid or expired
• 404 NOT_FOUND: No such row, or it belongs to someone else (the two are deliberately indistinguishable)

8. Mark NotificationOne as Read

Purpose:Purpose: MarkCall when the user taps a single notification as readrow.

Endpoint:Endpoint: PUT {base_url}/notifications/{notificationId}/read

Access Level:Level: 🔒 Protected (Requiresown Bearerrows Token Authentication)only)

Authentication:Authentication: Bearer Token

Request Headers

Path Parameters

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification marked as read",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:25:00.000000000",
  "data": null
}

Error

Marking Responsea JSONrow Sample

{is "success":already false,read "httpStatus":succeeds "NOT_FOUND",and "message":changes "Notificationnothing — safe to
retry. The badge is not foundsent back; subtract 1 locally.

Standard Error Types:


401 UNAUTHORIZED: Token missing, invalid or accessexpired
denied",
404 "action_time"NOT_FOUND: "2025-10-26T10:30:45",No "data":such "Notificationrow, or not foundyours
or access denied"
}

9. Mark Multiple NotificationsSeveral as Read

Purpose:Purpose: Mark multiplea notifications asselection read in aone single requestcall.

Endpoint:Endpoint: PUT {base_url}/notifications/read

Access Level:Level: 🔒 Protected (Requiresown Bearerrows Token Authentication)only)

Authentication:Authentication: Bearer Token

Request Headers

Request JSON Sample

{
  "notificationIds": [
    "123e4567-e89b-12d3-a456-426614174000"6e902bb6-9b38-49c6-825e-22b951f39584",
    "223e4567-e89b-12d3-a456-426614174002",
    "323e4567-e89b-12d3-a456-426614174003"0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f"
  ]
}

Request Body Parameters

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "32 notification(s) marked as read",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:25:00.000000000",
  "data": null
}

All or nothing: if even one id is missing or belongs to someone else, no row is changed and the call returns 400. Drop ids of rows you have deleted before sending.

Error Response JSON Sample

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Some notifications not found or access denied",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:25:00.000000000",
  "data": "Some notifications not found or access denied"
}

Standard Error Types:

• 400 BAD_REQUEST: A listed id is missing or not yours; nothing was changed
• 401 UNAUTHORIZED: Token missing, invalid or expired
• 422 UNPROCESSABLE_ENTITY: notificationIds is empty

10. Mark All Notifications as Read

Purpose:Purpose: The "Mark all unread notifications for the authenticated user as readread" button.

Endpoint:Endpoint: PUT {base_url}/notifications/read-all

Access Level:Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication:Authentication: Bearer Token

Request Headers

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "All notifications marked as read",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:25:00.000000000",
  "data": null
}

Set the badge to 0 locally afterwards.

Standard Error Types:

• 401 UNAUTHORIZED: Token missing, invalid or expired

11. Delete Notification( DON'T USE)

Purpose:Purpose: DeleteSwipe ato single notification permanentlydelete.

Endpoint:Endpoint: DELETE {base_url}/notifications/{notificationId}

Access Level:Level: 🔒 Protected (Requiresown Bearerrows Token Authentication)only)

Authentication:Authentication: Bearer Token

Request Headers

Path Parameters

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification deleted successfully",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:25:00.000000000",
  "data": null
}

Error

Deleting Responsean JSON Sample

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-26T10:30:45",
  "data": "Notification not found or access denied"
}

12. Batch Delete Notifications( DON'T USE)

Purpose:unread Deleterow multiplelowers notificationsthe inunread acount single— requestadjust the badge. Deleted rows cannot be recovered.

Endpoint:Standard Error Types:

• 401 UNAUTHORIZED: Token missing, invalid or expired
• 404 NOT_FOUND: No such row, or not yours

12. Delete Several

Purpose: Delete a selection in one call.

Endpoint: DELETE {base_url}/notifications/batch

Access Level:Level: 🔒 Protected (Requiresown Bearerrows Token Authentication)only)

Authentication:Authentication: Bearer Token

Request

Headers

This

Request JSON Sample

{
  "notificationIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174002",
    "323e4567-e89b-12d3-a456-426614174003"6e902bb6-9b38-49c6-825e-22b951f39584"
  ]
}

Request Body Parameters

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "1 notification(s) deleted successfully",
  "action_time": "2026-09-18T19:25:00.000000000",
  "data": null
}

All or nothing, like endpoint 9: one bad id and nothing is deleted.

Standard Error Types:

• 400 BAD_REQUEST: A listed id is missing or not yours; nothing was deleted
• 401 UNAUTHORIZED: Token missing, invalid or expired
• 422 UNPROCESSABLE_ENTITY: notificationIds is empty

13. Delete All Read

Purpose: The "Clear read" button — removes every row already read. Unread rows stay.

Endpoint: DELETE {base_url}/notifications/read

Access Level: 🔒 Protected

Authentication: Bearer Token

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "3 notification(s) deleted successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": null
}

Error Response JSON Sample

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Some notifications not found or access denied",
  "action_time": "2025-10-26T10:30:45",
  "data": "Some notifications not found or access denied"
}

13. Delete All Read Notifications( DON'T USE)

Purpose: Delete all read notifications for the authenticated user

Endpoint: DELETE {base_url}/notifications/read

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "15 read notification(s) deleted successfully",
  "action_time": "2025-10-26T10:30:45"2026-09-18T19:25:00.000000000",
  "data": 153
}

Success Response Fields

The

14.badge Createdoes In-Appnot Notification(change DON'T— USE)

Purpose:read Createrows awere new in-app notification (Internal service-to-service endpoint)removed.

Endpoint: POST {base_url}/notifications/in-app

Access Level: 🔒 Protected (Requires API Key or Service Authentication)

Authentication: API Key or Service Token

Request Headers

Request JSON Sample

{
  "userId": "987fcdeb-51a2-43d7-9c4e-123456789abc",
  "shopId": "456e7890-e89b-12d3-a456-426614174001",
  "serviceId": "ORD-2024-001",
  "serviceType": "ORDER",
  "title": "Order Confirmed",
  "message": "Your order #ORD-2024-001 has been confirmed and is being processed",
  "type": "SUCCESS",
  "priority": "MEDIUM",
  "data": {
    "orderId": "ORD-2024-001",
    "amount": 150.00,
    "currency": "USD",
    "items": 3
  }
}

Request Body Parameters

Success Response JSON Sample

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification saved successfully",
  "action_time": "2025-10-26T10:30:45",
  "data": "123e4567-e89b-12d3-a456-426614174000"
}

Success Response Fields

Error Response JSON Sample

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "userId": "must not be null",
    "title": "must not be blank",
    "message": "must not be blank"
  }
}

Standard Error Types

Application-Level Exceptions (400-499)

• 400401 BAD_REQUEST:UNAUTHORIZED: GeneralToken missing, invalid request data, random exceptions, or item already exists
• 401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
• 403 FORBIDDEN: Access denied, permission issues, verification failures, expired invitations
• 404 NOT_FOUND: Requested resource does not exist
• 422 UNPROCESSABLE_ENTITY: Validation errors with detailed field information
• 429 TOO_MANY_REQUESTS: Rate limit exceeded

Server-Level Exceptions (500+)

• 500 INTERNAL_SERVER_ERROR: Unexpected server errors

ErrorIntegration Response ExamplesChecklist

Bad

Request
• -Badge Generalloads from unread-count on app start and on every return to the foreground
•  notification.added on the existing /api/v1/events stream sets the badge from unreadCount — no second stream
•  Pages start at 1; paging stops when hasNext is false; duplicate ids are dropped
•  title is shown as the sentence; message line hidden when ""
•  createdAt parsed as UTC
•  A tap marks the row read, then opens targetType + targetId
•  An unknown targetType stays on the bell list — no crash, no error
•  A 404 from the target screen shows that screen's "not available" state
•  Badge adjusted locally after mark-read and delete (400)

event comes back)
 Batch mark-read and batch delete send only ids still in the list

 Unknown keys in {data "success":and false,unknown "httpStatus":type "BAD_REQUEST",values "message":are "Userignored
ID cannot be null",
  "action_time": "2025-10-26T10:30:45",
  "data": "User ID cannot be null"
}

Unauthorized - Token Issues (401)

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-10-26T10:30:45",
  "data": "Token has expired"
}

Forbidden - Access Denied (403)

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Access denied: Insufficient permissions",
  "action_time": "2025-10-26T10:30:45",
  "data": "Access denied: Insufficient permissions"
}

Not Found (404)

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-26T10:30:45",
  "data": "Notification not found or access denied"
}

Validation Error (422)

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-26T10:30:45",
  "data": {
    "userId": "must not be null",
    "title": "must not be blank",
    "serviceType": "must not be blank",
    "priority": "must not be blank"
  }
}

Quick Reference Guide

Common HTTP Status Codes

• 200 OK:OK: Successful GET/PUT request
• 201 Created: Successful POST request
• 204 No Content: Successful DELETE request
• 400 Bad Request:Request: Invalid request data (e.g. page=0, an id that is not yours in a batch)
• 401 Unauthorized:Unauthorized: Authentication required/failed
• 403 Forbidden: Insufficient permissions
• 404 Not Found:Found: ResourceRow does not foundexist or is not yours
• 422 Unprocessable Entity:Entity: Validation errors (empty notificationIds)
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error:Error: Server error

Authentication Types

• Bearer Token:Token: Include Authorization: Bearer your_token<accessToken> in headers (for user endpoints)
• API Key: Include X-API-Key: your_key in headers (for service-to-service endpoints)

Data Format Standards

• Dates:Dates Use: ISO 86018601, formatUTC without an offset (2025-10-26T14:30:00)2026-09-18T19:18:40.736493)
• IDs:IDs All IDs use: UUID formatstrings
• Pagination:Pagination Uses 1-based page numbering
• Boolean Fields: Use: true or falsepage (notfrom 1/0)1) and size; response carries currentPage, totalPages, hasNext

Notification Types

• INFO: General informational notifications
• WARNING: Warning or caution notifications
• ERROR: Error or failure notifications
• SUCCESS: Success or confirmation notifications

Priority Levels

• LOW: Low priority, can be checked later
• MEDIUM: Normal priority
• HIGH: High priority, needs attention soon
• URGENT: Urgent priority, requires immediate attention

Service Types

• ORDER: Order-related notifications
• PAYMENT: Payment-related notifications
• SHIPPING: Shipping and delivery notifications
• PRODUCT: Product-related notifications
• ACCOUNT: Account and profile notifications