Skip to main content

​
Standard envelope

All API responses from the Zeam gateway — both success and error — are wrapped in a standard envelope: 
{
  "data": { ... },
  "status": 200,
  "message": "OK"
}
FieldTypeDescription
dataobject, array, scalar, or nullThe response payload. null for errors.
statusintegerThe HTTP status code — always matches the status on the wire.
messagestringA human-readable summary of the result.

​
Success responses

For successful requests, data contains the response payload and status reflects the HTTP status code: 
{
  "data": {
    "transactionId": "abc-123",
    "status": "completed"
  },
  "status": 200,
  "message": "OK"
}

​
Error responses

For errors, data is null and message includes a machine-readable error code prefix: 
{
  "data": null,
  "status": 422,
  "message": "missing_field: amount is required"
}
The error code before the colon (e.g., missing_field) is stable and safe to match programmatically. The description after the colon may change between releases. See Errors for the full error classification table and retry guidance.

​
Data unwrapping

Some API responses already include a data wrapper. The gateway automatically unwraps these to prevent double nesting. 
{
  "data": {
    "userId": "abc",
    "handle": "john"
  },
  "success": true,
  "message": "User retrieved"
}
Without unwrapping, the response would contain data.data — the gateway ensures this never happens. When the original response does not contain a data field, the entire response body is placed inside data: 
{
  "id": "acc-1",
  "balance": "100.00",
  "currency": "ZAR"
}

​
Exceptions

/auth-connect* routes (Ed25519 authentication) return bare JSON without the standard envelope. This matches the Stellar Ed25519 protocol specification. See Ed25519 app auth for details.

​
HTTP status codes

The status field in the envelope always mirrors the HTTP status code on the wire. Your HTTP client can rely on either — they are guaranteed to match.
CodeMeaning
200Synchronous read or mutation returning final state
201Resource created
202Asynchronous mutation accepted — poll for result
204Successful delete — no response body
4xxClient error — see Errors
5xxServer error — retry with backoff