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

# Response Structure

> Standardized request and response patterns for the Research Desk Demand API

All endpoints accept and return JSON. The `Content-Type` header for POST and PATCH requests must be `application/json`.

## Success Responses

Successful requests return HTTP `2xx` status codes. The response body contains the requested object or array directly — there is no outer wrapper envelope.

**Single object example (GET /surveys/{id}):**

```json theme={null}
{
  "id": "abc-123",
  "name": "US Gen Pop Q2 2025",
  "status": "Live",
  "country": "US"
}
```

**List example (GET /surveys):**

```json theme={null}
[
  { "id": "abc-123", "name": "US Gen Pop Q2 2025", ... },
  { "id": "def-456", "name": "UK Millennials", ... }
]
```

## Error Responses

All error responses return a JSON body with a `message` field containing a human-readable description suitable for display to end users.

<Tabs>
  <Tab title="400 Bad Request">
    Returned when a required field is missing or a field value is invalid.

    ```json theme={null}
    {
      "message": "Survey name is required."
    }
    ```
  </Tab>

  <Tab title="401 Unauthorized">
    Returned when the `Authorization` header is missing, expired, or invalid.

    ```json theme={null}
    {
      "message": "Unauthorized."
    }
    ```
  </Tab>

  <Tab title="404 Not Found">
    Returned when the requested resource does not exist or is not accessible under your account.

    ```json theme={null}
    {
      "message": "Survey could not be found."
    }
    ```
  </Tab>

  <Tab title="405 Method Not Allowed">
    Returned when an unsupported HTTP method is used — for example, attempting to DELETE a resource.

    ```json theme={null}
    {
      "message": "Survey objects cannot be deleted."
    }
    ```
  </Tab>

  <Tab title="429 Too Many Requests">
    Returned when a rate limit is exceeded. See [Rate Limits](/demand/overview/02-rate-limits) for per-endpoint limits and retry guidance.

    ```json theme={null}
    {
      "message": "Too many requests. Please try again later."
    }
    ```
  </Tab>

  <Tab title="500 Server Error">
    Returned when an unexpected server-side error occurs. If this persists, contact [clientsuccess@repdata.com](mailto:clientsuccess@repdata.com).

    ```json theme={null}
    {
      "message": "Our server experienced an unexpected error."
    }
    ```
  </Tab>
</Tabs>

## HTTP Status Code Reference

| Code                        | Meaning          | Common Cause                                     |
| --------------------------- | ---------------- | ------------------------------------------------ |
| `200 OK`                    | Success          | Standard success for GET and PATCH               |
| `201 Created`               | Resource created | Success for POST (create) requests               |
| `400 Bad Request`           | Validation error | Missing required field or invalid value          |
| `401 Unauthorized`          | Auth failure     | Missing, expired, or invalid token               |
| `404 Not Found`             | Resource missing | Wrong ID or insufficient account permissions     |
| `405 Method Not Allowed`    | Invalid method   | Attempting DELETE or unsupported verb            |
| `429 Too Many Requests`     | Rate limited     | Request volume exceeded per-endpoint limit       |
| `500 Internal Server Error` | Server error     | Unexpected error — contact support if persistent |

## Pagination

Endpoints that return lists (`GET /surveys`, `GET /responses`) support pagination via query parameters:

| Parameter   | Type    | Description                                             |
| ----------- | ------- | ------------------------------------------------------- |
| `page`      | integer | Page number, starting at `1` (default: `1`)             |
| `page_size` | integer | Number of results per page (default varies by endpoint) |

Example: `GET /surveys?page=2&page_size=50`

<Tip>
  When polling for responses during active fieldwork, combine pagination with a timestamp filter where supported to retrieve only new records since your last poll.
</Tip>