# CRM · Audiences

Part of AppEngine API Documentation. Full index: https://appengine.appmint.io/documentation.md
## GET /crm/marketing/audiences/segments

**List audience segments**

`operationId: AudienceController_getAudienceSegments`

The audience segments defined for the org.

#### Signature

```http
GET /crm/marketing/audiences/segments (status?: string, platforms?: string, sizeMin?: integer, sizeMax?: integer, ageMin?: integer, ageMax?: integer, locations?: string, interests?: string, behaviors?: string, createdBy?: string, search?: string, page?: string, limit?: string, sortField?: string, sortDirection?: string) -> Audience segments, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /crm/marketing/audiences/segments/{id}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `status` | query | string | — | Filter by status. |
| `platforms` | query | string | — | Comma-separated platforms. |
| `sizeMin` | query | integer | — | Minimum audience size. |
| `sizeMax` | query | integer | — | Maximum audience size. |
| `ageMin` | query | integer | — | Minimum age. |
| `ageMax` | query | integer | — | Maximum age. |
| `locations` | query | string | — | Comma-separated locations. |
| `interests` | query | string | — | Comma-separated interests. |
| `behaviors` | query | string | — | Comma-separated behaviors. |
| `createdBy` | query | string | — | Creator email. |
| `search` | query | string | — | Search text. |
| `sortDirection` | query | "asc" \| "desc" | — |  |
| `page` | query | string | — | Page number (1-based). |
| `limit` | query | string | — | Maximum rows. |
| `sortField` | query | string | — | Field to sort by. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Audience segments, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /crm/marketing/audiences/segments

**Create an audience segment**

`operationId: AudienceController_createAudienceSegment`

Defines a reusable audience from targeting criteria, so campaigns can reference it instead of restating the rules.

Note `createdBy` is a **query parameter** defaulting to the literal string `api` — it is not taken from the authenticated user, so pass it explicitly if you want a real name in the audit trail.

#### Signature

```http
POST /crm/marketing/audiences/segments (createdBy?: string, body) -> The created segment, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Responses on this controller are wrapped as `{ success, data, message }` rather than returning the record bare.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /crm/marketing/audiences/estimate-reach`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `createdBy` | query | string | — | Recorded as the creator. Defaults to the literal string `api`, **not** the calling user. |

### Request body

The segment to create.

```json
{
  "name": "High-value repeat buyers",
  "description": "Three or more orders over $200",
  "criteria": {
    "minOrders": 3,
    "minLifetimeValue": 200
  }
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The created segment, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /crm/marketing/audiences/segments/{id}

**Get an audience segment**

`operationId: AudienceController_getAudienceSegment`

Fetches one segment with its criteria and estimated reach.

#### Signature

```http
GET /crm/marketing/audiences/segments/{id} (id: string) -> The segment, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `PUT /crm/marketing/audiences/segments/{id}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `id` | path | string | yes | Audience segment id. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The segment, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## PUT /crm/marketing/audiences/segments/{id}

**Update an audience segment**

`operationId: AudienceController_updateAudienceSegment`

Updates a segment's criteria or details. Changing criteria changes who is in the audience for **future** campaigns; campaigns already sent are unaffected.

#### Signature

```http
PUT /crm/marketing/audiences/segments/{id} (id: string, updatedBy?: string, body) -> The updated segment, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `DELETE /crm/marketing/audiences/segments/{id}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `id` | path | string | yes | Audience segment id. |
| `updatedBy` | query | string | — | Who made the change (recorded on the record). |

### Request body

Fields to change.

```json
{
  "criteria": {
    "minOrders": 5,
    "minLifetimeValue": 500
  }
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The updated segment, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## DELETE /crm/marketing/audiences/segments/{id}

**Delete an audience segment**

`operationId: AudienceController_deleteAudienceSegment`

Deletes a segment. Campaigns still referencing it lose their targeting — check what uses it before deleting.

#### Signature

```http
DELETE /crm/marketing/audiences/segments/{id} (id: string, deletedBy?: string) -> Deletion result, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Nothing checks for campaigns using the segment first.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /crm/marketing/audiences/segments`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `id` | path | string | yes | Audience segment id. |
| `deletedBy` | query | string | — | Who deleted it (recorded). |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Deletion result, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /crm/marketing/audiences/custom

**List custom audiences**

`operationId: AudienceController_getCustomAudiences`

The platform-specific custom audiences, optionally filtered by platform or type.

#### Signature

```http
GET /crm/marketing/audiences/custom (platform?: string, type?: string) -> Custom audiences, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /crm/marketing/audiences/custom-types`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `platform` | query | string | — |  |
| `type` | query | string | — |  |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Custom audiences, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /crm/marketing/audiences/custom

**Create a custom audience**

`operationId: AudienceController_createCustomAudience`

Creates a platform-specific custom audience — an uploaded list or a lookalike — as opposed to a criteria-based segment.

#### Signature

```http
POST /crm/marketing/audiences/custom (createdBy?: string, body) -> The created custom audience, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Uploading customer data to an ad platform carries its own consent obligations — this endpoint does not check them.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /crm/marketing/audiences/custom`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `createdBy` | query | string | — | Recorded as the creator. Defaults to the literal string `api`, **not** the calling user. |

### Request body

The custom audience to create.

```json
{
  "name": "Newsletter subscribers",
  "platform": "facebook",
  "type": "customer_list"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The created custom audience, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /crm/marketing/audiences/segments/{id}/insights

**Get audience insights**

`operationId: AudienceController_getAudienceInsights`

Demographic and behavioural breakdown of who is in a segment — what the audience actually looks like, rather than just how large it is.

#### Signature

```http
GET /crm/marketing/audiences/segments/{id}/insights (id: string) -> Audience insights, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /crm/marketing/audiences/segments/{id1}/overlap/{id2}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `id` | path | string | yes | Audience segment id. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Audience insights, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /crm/marketing/audiences/estimate-reach

**Estimate audience reach**

`operationId: AudienceController_estimateAudienceReach`

Estimates how many people match a set of criteria **without creating a segment** — the way to size an audience while building it, before committing to it.

#### Signature

```http
POST /crm/marketing/audiences/estimate-reach (body) -> The estimated reach, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Creates nothing — safe to call repeatedly while tuning criteria.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /crm/marketing/audiences/segments`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

The criteria to size.

```json
{
  "criteria": {
    "minOrders": 3,
    "minLifetimeValue": 200
  }
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The estimated reach, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

Example response:

```json
{
  "success": true,
  "data": {
    "estimatedReach": 4200
  }
}
```

## GET /crm/marketing/audiences/segments/{id1}/overlap/{id2}

**Get overlap between two audiences**

`operationId: AudienceController_getAudienceOverlap`

How much two segments share. Worth checking before running campaigns against both — a large overlap means the same people receive both, which reads as spam and skews per-campaign attribution.

#### Signature

```http
GET /crm/marketing/audiences/segments/{id1}/overlap/{id2} (id1: string, id2: string) -> The overlap, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /crm/marketing/audiences/segments/{id}/insights`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `id1` | path | string | yes | First segment. |
| `id2` | path | string | yes | Second segment. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The overlap, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /crm/marketing/audiences/interests

**List targetable interests**

`operationId: AudienceController_getPopularInterests`

The interest categories available for targeting — the vocabulary a segment's criteria can draw on.

#### Signature

```http
GET /crm/marketing/audiences/interests (category?: string) -> Interests, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /crm/marketing/audiences/targeting-options`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `category` | query | string | — |  |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Interests, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /crm/marketing/audiences/locations

**List targetable locations**

`operationId: AudienceController_getLocationSuggestions`

The geographic locations available for targeting.

#### Signature

```http
GET /crm/marketing/audiences/locations (query?: string) -> Locations, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /crm/marketing/audiences/targeting-options`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `query` | query | string | — | Location search text. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Locations, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /crm/marketing/audiences/custom-types

**List custom audience types**

`operationId: AudienceController_getCustomAudienceTypes`

The kinds of custom audience that can be created — customer list, lookalike, engagement-based and so on.

#### Signature

```http
GET /crm/marketing/audiences/custom-types () -> Custom audience types, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /crm/marketing/audiences/custom`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Custom audience types, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /crm/marketing/audiences/targeting-options

**List all targeting options**

`operationId: AudienceController_getTargetingOptions`

Every dimension a segment can target on, in one call — build a targeting UI from this rather than fetching interests and locations separately.

#### Signature

```http
GET /crm/marketing/audiences/targeting-options (orgId?: string) -> Targeting options, wrapped
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /crm/marketing/audiences/interests`
- `GET /crm/marketing/audiences/locations`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | query | string | — | Organization id (the `orgid` header is what scopes the request). |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Targeting options, wrapped |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |