Skip to content
MACHHUB MACHHUB MACHHUB
Contribute to this page

Conventions & errors

This page covers the response conventions shared across the MACHHUB REST API: success and error shapes, the correlation header, and the list query-parameter grammar.

Success responses

Section titled “Success responses”

Successful responses are JSON. Many endpoints wrap their payload in a success envelope:

{ "success": true }
{ "success": true, "status": { "active": true, "type": "trial" } }

List and get endpoints often return the data directly (an array or object) rather than an envelope. Treat a 2xx status as success and read the body accordingly.

Error responses

Section titled “Error responses”

Errors return an appropriate HTTP status with a plain-text message body — not JSON. For example, a failed login returns:

HTTP/1.1 401 Unauthorized
Content-Type: text/plain


Invalid Username or Password

Common statuses you will see:

StatusMeaning
400 Bad RequestMalformed body or invalid parameter (e.g. bad Domain ID)
401 UnauthorizedMissing/invalid credential, or action not allowed
409 ConflictResource already exists (e.g. duplicate collection or upstream)
422 Unprocessable ContentValid request, unacceptable content (e.g. wrong file type)
500 Internal Server ErrorUnexpected server-side failure
503 Service UnavailableA dependency could not be reached (e.g. an upstream broker)

Because error bodies are plain text, read them as text rather than parsing JSON:

if (!response.ok) {
  const message = await response.text();
  throw new Error(message || `HTTP ${response.status}`);
}

The App-CorrelationID header

Section titled “The App-CorrelationID header”

Every response carries an App-CorrelationID header. The value is assigned per request by the correlation middleware and is included in server log lines, so quote it when reporting an issue to correlate a client failure with server logs.

HTTP/1.1 200 OK
App-CorrelationID: 6f1c2a9e-1b34-4f0a-9c2e-77f0b1a2c3d4

List query parameters

Section titled “List query parameters”

List endpoints (for example GET /machhub/:table_name/all) accept query parameters for filtering, sorting, and pagination:

ParameterFormExample
Filterfilter[field][op][type]=valuefilter[status][eq][string]=active
Sortsort=[field][dir]sort=[created_dt][desc]
Limitlimit=<n>limit=50
Offsetoffset=<n>offset=100
GET /machhub/products/all?filter[price][gt][number]=10&sort=[name][asc]&limit=20&offset=0

The SDK builds these for you through its fluent query API, so you rarely assemble them by hand.

Security

Section titled “Security”
Section titled “Related”