DEV - Response Structure | DOCS - SweetConnect Platform

Overview

SweetConnect APIs use shared response formats for successful results and errors. The exact response schema for each operation is documented in the API reference.

SweetConnect APIs follow REST principles and use standard HTTP methods and status codes. Successful requests typically return a status code in the 2xx range, client errors use 4xx, and server errors use 5xx.

The API reference specifies the exact response status and schema for each operation. Some operations, such as file downloads or redirects, use a response format specific to that operation instead of the standard JSON structure.

Success Responses

Successful requests that return JSON usually wrap their result in a data field:

{
  "data": {
    "id": "resource-id"
  }
}

Depending on the operation, data can contain an object, an array, or a simple value such as a string, number, or boolean.

List Responses

Operations that return multiple items use an array in the data field:

{
  "data": [
    {
      "id": "resource-1"
    },
    {
      "id": "resource-2"
    }
  ]
}

An empty result is represented by an empty array:

{
  "data": []
}

Paginated Responses

Paginated operations return the items in data and pagination information in a separate meta field:

{
  "data": [
    {
      "id": "resource-1"
    }
  ],
  "meta": {
    "page": 1,
    "offset": 0,
    "limit": 10,
    "totalItems": 100,
    "totalPages": 10,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Field	Description
`page`	Current page number
`offset`	Number of items skipped before the current page
`limit`	Maximum number of items returned per page
`totalItems`	Total number of available items
`totalPages`	Total number of available pages
`hasNextPage`	Indicates whether another page follows
`hasPreviousPage`	Indicates whether a previous page exists

Responses Without Content

Some successful operations return 204 No Content. These responses do not contain a response body.

Error Responses

Errors returned by SweetConnect APIs usually contain an errors array:

{
  "errors": [
    {
      "errorCode": "RequestValidationError",
      "message": "The request is invalid.",
      "extension": {
        "type": "body",
        "key": "name"
      }
    }
  ]
}

Field	Required	Description
`errors`	Yes	Contains one or more error objects
`errorCode`	Yes	Machine-readable identifier for the error
`message`	No	Human-readable description of the error
`extension`	No	Additional structured information related to the error

Applications should use errorCode for programmatic error handling. The text in message is intended for humans and should not be parsed to identify an error. The content of extension depends on the corresponding error code.

Multiple Errors

A response can contain multiple errors, for example when several request fields fail validation:

{
  "errors": [
    {
      "errorCode": "RequestValidationError",
      "message": "The name field is required.",
      "extension": {
        "type": "body",
        "key": "name"
      }
    },
    {
      "errorCode": "RequestValidationError",
      "message": "The languageCode field is invalid.",
      "extension": {
        "type": "body",
        "key": "languageCode"
      }
    }
  ]
}

Clients should process the complete errors array instead of relying only on its first element.

The API reference lists the documented status codes and error schemas for each operation.

Response Structure