Errors & Status Codes¶

All API errors return a JSON body alongside an appropriate HTTP status code.

Error Response Format¶

{
  "Message": "Human-readable description of the error.",
  "Code": "Domain.Subtype"
}

Field	Type	Description
`Message`	string	A human-readable explanation suitable for logging or display
`Code`	string	A machine-readable error code in `Domain.Subtype` format

HTTP Status Codes¶

Status	Meaning
`200 OK`	Request succeeded
`400 Bad Request`	Validation failed or the request body is malformed
`401 Unauthorized`	Missing or invalid authentication token
`403 Forbidden`	Authenticated, but the user lacks the required privilege
`404 Not Found`	The requested resource does not exist
`422 Unprocessable Entity`	Missing CSRF token on a state-modifying request
`500 Internal Server Error`	Unexpected server error

Purchase Order Error Codes¶

Resource Not Found¶

Code	Message	Trigger
`PurchaseOrderList.NotFound`	PO #{id} not found	`GET/PUT/DELETE /api/purchase-order/{id}` with unknown id
`PurchaseOrderDetails.NotFound`	PO Detail #{id} not found	`DELETE /api/purchase-order-details/{id}` with unknown id

Referential Integrity¶

Code	Message	Trigger
`PurchaseOrderList.StillInUse`	PO #{number} is still in use	`DELETE` on a PO referenced by other records
`PurchaseOrderDetails.StillInUse`	PO Detail #{id} is still in use	`DELETE` on a detail line referenced by other records

Validation¶

Code	Message	Trigger
`OrderList.NoItems`	Purchase order must contain at least one item	`POST/PUT` with empty `details` array
`OrderList.MultipleWarehouses`	All items must be for the same warehouse	`POST/PUT` with line items from different warehouses
`OrderDetails.DuplicateRows`	Duplicate entries found in order details	`POST/PUT` with repeated item/sub-item combinations
`PurchaseOrderDetails.OrderDateAfterShip`	Order date cannot be after ship date	`POST/PUT` with `Order Date > Ship Date`
`JSON.Invalid`	Bad Request Format	Malformed or missing JSON body

Master Data¶

Code	Message	Trigger
`ItemMaster.NotFound`	Item {number} not found in Item Master	Line item references an unknown item number
`SupplierMaster.NotFound`	Supplier {number} not found	PO references an unknown supplier number
`WarehouseMaster.NotFound`	Warehouse {number} not found	Line item references an unknown warehouse number
`ShipFromMaster.NotFound`	Ship From {number} not found	Line item references an unknown ship-from location

Access Control¶

Code	Message	HTTP
`User.NotPrivileged`	Not Privileged for this action	403

Notification Types¶

Create, update, and move operations may return a notification in the response body instead of (or in addition to) an error. This occurs when the operation is queued because the procurement tables are locked during an integration run.

{
  "message": "Changes will be visible after the integration is done.",
  "notification_type": "Warning"
}

`notification_type`	Meaning
`Warning`	Operation accepted and queued; no immediate confirmation
`Success`	Operation completed immediately

Troubleshooting¶

I receive 401 on every request. - Ensure your HTTP client sends cookies automatically. - Check that the access_token_cookie cookie is present in the response from /api/login. - The token may have expired - call /api/refresh with the refresh_token_cookie.

I receive 403 User.NotPrivileged. - Your user account does not have the required privilege for this endpoint. Contact your Knosc administrator to update your role.

I receive 422 on POST/PUT/DELETE. - Include the X-XSRF-TOKEN header. Read its value from the csrf_access_token cookie set during login.

My POST returns a Warning notification. - A data integration is currently running and the procurement tables are locked. Your change has been queued and will be applied automatically when the integration completes.

ItemMaster.NotFound on a known item. - Confirm the Item Number value matches exactly (case-sensitive). Use the Item Master API to verify.