Responses and Errors

Universal API responses use the same public envelope across apps.

The provider response is mapped into a MindCloud response before it reaches your code. That means your application can read the same top-level fields even when different apps return different native shapes.

Successful responses

Successful requests return JSON with success: true.

{
  "success": true,
  "data": [],
  "meta": {}
}

Field	What it contains
`success`	`true` when the action completed successfully.
`data`	The mapped action rows.
`meta`	Safe metadata when available.

data is an array. For actions that map a single provider object, MindCloud returns an array with one item.

Data rows

Actions return mapped rows in data:

{
  "success": true,
  "data": [
    {
      "id": "U123",
      "name": "Ava"
    },
    {
      "id": "U456",
      "name": "Ben"
    }
  ]
}

Use fields when you only need part of each item. Use limit and offset when the action supports pagination.

Single-row responses

Create, update, delete, and read-one actions can still return a single mapped row. It is returned inside the data array:

{
  "success": true,
  "data": [
    {
      "id": "C123",
      "name": "Engineering"
    }
  ]
}

The exact fields depend on the selected action and provider response, but the public data shape remains an array.

Metadata

meta contains safe metadata when MindCloud has something useful to expose.

{
  "success": true,
  "data": [],
  "meta": {
    "pagination": {
      "hasNextPage": false
    }
  }
}

Not every response includes meta. Do not require metadata to exist unless the action page or response you receive includes it.

MindCloud does not expose provider credentials or internal transport details in the public response.

Error responses

Failed requests return success: false with a public error message.

{
  "success": false,
  "code": "CONNECTION_APP_MISMATCH",
  "message": "Connection \"conn_123\" is not configured for this app."
}

The exact code depends on where the request failed. Your code should treat message as human-readable and code as the stable value to branch on when a code is present.

Common errors

Most Universal API errors come from one of these cases:

Case	What to check
Missing or invalid API Key	Send `Authorization: Bearer $MINDCLOUD_API_KEY`.
Missing `connectionId`	Query string for `GET` and `DELETE`; body for `POST`, `PUT`, and `PATCH`.
Wrong app connection	The connection must belong to the app you are calling.
Unknown app, version, or action	Check the URL path and selected app version.
Wrong HTTP method	Use the method shown on the action page.
Invalid arguments	Check required fields, data types, and JSON shape.
Provider rejection	Check the connected app account, permissions, and provider-side validation.

Status codes

Use the HTTP status code first.

Authentication and authorization failures use 401 or 403. Invalid request shape usually uses 400. Provider or upstream failures can return 5xx status codes when MindCloud cannot complete the action.

The JSON body gives the specific public code and message when available.

Usage

Each Universal API request runs an action and counts as account usage.

Account admins can review usage and manage billing in Usage & Billing.