API Conventions

Response Envelope

Shared success, error, and paginated JSON envelope shapes.

FutureSMS JSON responses use stable envelopes so clients can parse the outer shape consistently. This page explains what each envelope field carries. Endpoint-specific payload fields and status-code meanings are documented on each workflow page.

Success envelope

Successful JSON responses use message, details, data, and meta.

Success shape

{
  "message": "Accepted",
  "details": "Bulk execution command accepted",
  "data": {
    "bulk_job_id": "BKJ-9001"
  },
  "meta": {}
}

Field	Type	Carries
`message`	`string`	Canonical result word such as `OK`, `Created`, or `Accepted`. It is stable and safe to show as a primary message.
`details`	`string \| null`	Optional operation-specific secondary text, such as `Bulk execution command accepted`. It is present in the shape, but may be `null` when there is no useful safe detail.
`data`	`object \| array \| null`	Endpoint-specific success payload, such as an order, a bulk job, a token response, or a list of rows.
`meta`	`object \| null`	Non-primary metadata for client logic, such as pagination.

message should not carry business data. Read business data from data, and read list metadata from meta.

Error envelope

Core Merchant API errors use error_code, reason, message, details, path, timestamp, and request_id. Error bodies do not contain data or meta.

Error shape

{
  "error_code": "VALIDATION_ERROR",
  "reason": "PASSWORD_TOO_SHORT",
  "message": "Validation failed",
  "details": "New password must be at least 8 characters",
  "path": "/api/v1/auth/change-password",
  "timestamp": "2026-04-11T00:00:00Z",
  "request_id": "req_20260411_demo_0001"
}

Field	Type	Carries
`error_code`	`string`	Coarse machine-readable category, usually aligned with the HTTP status, such as `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_ERROR`, or `TOO_MANY_REQUESTS`.
`reason`	`string \| null`	More precise machine-readable reason for client state machines, such as `INVALID_CREDENTIALS`, `TOKEN_EXPIRED`, or `PASSWORD_TOO_SHORT`.
`message`	`string`	Safe primary human-readable error message.
`details`	`string \| null`	Safe secondary human-readable detail. It may be `null` when the detail would reveal sensitive information or there is no useful extra text.
`path`	`string`	Request path that produced the error.
`timestamp`	`date-time`	Time the error response was produced.
`request_id`	`string`	Request identifier for support and tracing. Include this when asking FutureSMS support to investigate a failed request.

message and details are the browser-visible fields. Machine handling should use error_code and, when present, reason.

Pagination metadata

List responses put rows in data and pagination in meta.pagination.

Paginated shape

{
  "message": "OK",
  "details": "Bulk job items returned",
  "data": [
    {
      "bulk_job_item_id": "BKI-12001",
      "row_no": 1
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 52
    }
  }
}

Field	Type	Carries
`meta.pagination.page`	`integer`	1-based current page number.
`meta.pagination.limit`	`integer`	Requested page size limit.
`meta.pagination.total`	`integer`	Total number of rows matching the filter before pagination.

Authentication

Pagination

Shared list paging and sorting conventions.