> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poelis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Format

> Success and error response structures for the Poelis API

All responses are JSON. This page describes the response shapes you will see across endpoints.

## Content Type

* **Success**: `Content-Type: application/json`
* **Errors**: `Content-Type: application/json` (same as success; distinguish by HTTP status code)

## Success Responses

### List Endpoints (Collections)

These list endpoints use this shape: [List workspaces](/api-reference/workspaces/list-workspaces), [List products](/api-reference/products/list-products-in-a-workspace), [List items](/api-reference/items/list-items-in-a-product), [List properties](/api-reference/properties/list-properties-for-an-item).

```json theme={null}
{
  "items": [
    { "id": "...", "name": "...", ... }
  ],
  "count": 2
}
```

| Field   | Type    | Description                                    |
| ------- | ------- | ---------------------------------------------- |
| `items` | array   | Array of resource objects for the current page |
| `count` | integer | Number of items in this response (page size)   |

`count` is the length of `items`, not the total number of resources. Use [pagination](/api-reference/pagination) parameters to request more pages.

### Single Resource Endpoints

Endpoints that return one resource (e.g. get workspace by ID, get product by ID) return the resource object directly:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "readable_id": "ws-001",
  "name": "My Workspace"
}
```

No wrapper object; the response body is the resource.

## Common Resource Fields

Many resources include:

* **`id`**: UUID, stable unique identifier; use this for API calls.
* **`readable_id`**: Human-readable identifier (e.g. `ws-001`, `prod-abc`); is changeable inside Poelis.

## Error Responses

When the request fails, the API returns a JSON error body and a non-2xx status code. Structure:

```json theme={null}
{
  "error": "error_code",
  "message": "Error message",
  "details": {
    "field": "additional context"
  }
}
```

| Field     | Type   | Description                                        |
| --------- | ------ | -------------------------------------------------- |
| `error`   | string | Machine-readable code (e.g. `validation_error`)    |
| `message` | string | Error message                                      |
| `details` | object | Optional; extra context (e.g. field, retry\_after) |

`details` may be omitted for some errors. Always check the HTTP status code and `error` for handling logic. See [Status Codes](/api-reference/status-codes) and [Error Handling](/guides/error-handling) for all codes and examples.

## Response Headers

* **`X-Request-ID`**: Unique ID for the request. Include it when contacting support about an error.
* **`Retry-After`**: Present on `429 Too Many Requests`; seconds to wait before retrying (e.g. `"60"`).
* **`X-RateLimit-Limit`**, **`X-RateLimit-Remaining`**, **`X-RateLimit-Reset`**: Present on all responses; on 429, `X-RateLimit-Remaining` is `"0"` and `X-RateLimit-Reset` is the Unix timestamp (seconds) when the window resets.