# Kiteworks API Concepts — Pagination, Rate Limits & Status Codes

> Kiteworks REST API core concepts: pagination with offset/limit, result sorting, rate limiting, and HTTP status codes. Learn how the API behaves before making calls.

API Fundamentals

# Kiteworks API Concepts

Core behaviors that apply uniformly across every Kiteworks API endpoint — how to page through large result sets, sort responses, stay within rate limits, and interpret HTTP status codes and error bodies.

## Pagination

All list endpoints — folders, files, users, and other top-level resources — share a consistent pagination interface. Two query parameters control which slice of results is returned:

| Parameter | Type | Description |
|---|---|---|
| `limit` | integer | Maximum number of results to return in a single response. |
| `offset` | integer | Number of records to skip before the first result in the response. Use this with `limit` to page through a full result set. |

> When neither `limit` nor `offset` is specified, the API returns up to **25 records** by default. For resources with large record counts, always supply an explicit `limit` to keep response sizes predictable and avoid hitting rate limits.

### Example — paging through files

The pattern below retrieves records in pages of 50, advancing the `offset` by `limit` on each request until fewer results than the limit are returned.

cURL Python

paginate.sh Copy

```bash
# Page 1 — first 50 records
curl -s "https://demo.kiteworks.com/rest/files?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Page 2 — next 50 records
curl -s "https://demo.kiteworks.com/rest/files?limit=50&offset=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

paginate.py Copy

```python
import requests

def get_all_files(base_url: str, headers: dict, page_size: int = 50) -> list:
    """Fetch all files by paging through the API."""
    results = []
    offset = 0

    while True:
        resp = requests.get(
            f"{base_url}/rest/files",
            headers=headers,
            params={"limit": page_size, "offset": offset},
        )
        resp.raise_for_status()
        page = resp.json().get("data", [])
        results.extend(page)

        # Stop when the page is smaller than the requested limit
        if len(page) < page_size:
            break

        offset += page_size

    return results
```

## Sorting

List endpoints accept an `orderBy` query parameter that controls the order in which results are returned. Sorting is performed server-side, so you receive results in the requested order without any additional client-side processing.

### Syntax

The value of `orderBy` is a **field name** and **direction** joined by a colon:

orderBy format Copy

```bash
orderBy={fieldName}:{direction}

# direction must be one of:
#   asc   — ascending order  (A → Z, oldest → newest)
#   desc  — descending order (Z → A, newest → oldest)

# The colon must be URL-encoded as %3A in query strings:
?orderBy=name%3Aasc
```

### Example

The following request retrieves top-level folders sorted alphabetically by name:

sort-folders.sh Copy

```bash
curl -s "https://demo.kiteworks.com/rest/folders/top?orderBy=name%3Aasc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

> `orderBy` and `limit`/`offset` can be combined freely. Sort order is applied before pagination, so each page will reflect the requested ordering.

## Rate Limiting

Rate limits apply to every Kiteworks API endpoint and are enforced per IP address within a rolling time window. When a limit is exceeded the API returns `429 Too Many Requests`.

| Account type | Request limit | Queue depth |
|---|---|---|
| Standard | 30 requests / second / IP | Up to 40 requests queued before further calls are rejected |
| MFT application | 300 requests / second / IP | — |

The elevated MFT limit accommodates the high-volume, automated transfer patterns typical of managed file transfer operations.

### Staying within limits

Two practices will keep most integrations well inside the thresholds:

- **Cache access tokens.** Fetch a token once and reuse it until it expires — don't request a new token on every API call. See [Authorization Code — Python sample](authentication.html#ac-python) for an example caching implementation.
- **Apply exponential backoff on 429 responses.** Wait before retrying — start at 1 second, doubling on each subsequent attempt, to avoid hammering the endpoint while limits are in effect.

## HTTP Status Codes

The Kiteworks API uses standard HTTP response codes. Codes fall into three categories:

2xx Success

The request was received, understood, and processed successfully.

4xx Client Error

The request could not be completed due to a problem with the data or credentials supplied by the client — validation errors, missing parameters, or authentication failures.

5xx Server Error

An unexpected internal failure occurred. The request appeared valid but the server was unable to fulfill it.

### Status code reference

| Code | Name | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 201 | Created | A resource was created successfully. For action endpoints, the action completed successfully. |
| 204 | No Content | The resource was deleted successfully. No body is returned. |
| 401 | Unauthorized | Authentication is required and has failed or has not been provided. Verify your Bearer token is present and has not expired. |
| 403 | Forbidden | The request was valid but the server refused it — the authenticated user or application does not have permission to perform this operation. |
| 404 | Not Found | The requested resource does not exist or is not accessible to the authenticated user. |
| 409 | Conflict | The request conflicts with the current state of the resource — for example, attempting to create a resource that already exists. |
| 422 | Unprocessable Entity | The request was syntactically correct but could not be processed — usually caused by an invalid parameter value in the request body. The error response will identify the offending field. |
| 429 | Too Many Requests | The rate limit for your IP address has been exceeded. Wait for the number of seconds indicated in the `Retry-After` response header before retrying. |
| 490 | Blocked by WAF | The request was blocked by the Web Application Firewall. Review your request payload for content that may trigger WAF rules. |
| 503 | Service Unavailable | The server is temporarily unable to handle the request, typically due to scheduled maintenance. Retry after a short delay. |

## Error Response Body

All error responses include a JSON body with a consistent structure. Use the `code` field for programmatic error handling and `message` for logging or user-facing messaging.

| Field | Always present | Description |
|---|---|---|
| `code` | Yes | A machine-readable identifier for the error type, suitable for use in `switch` or conditional logic. |
| `field` | No | The name of the request parameter that caused the error. Present only on `422 Unprocessable Entity` responses, where a specific field value was invalid. |
| `message` | Yes | A human-readable description of what went wrong. Useful for logging and debugging, but should not be relied on programmatically as wording may change. |

### Example error responses

422 — Invalid field 401 — Unauthorized 403 — Forbidden

422 response Copy

```json
{
  "code": "INVALID_PARAMETER",
  "field": "email",
  "message": "The value provided for 'email' is not a valid email address."
}
```

401 response Copy

```json
{
  "code": "invalid_token",
  "message": "The access token has expired. Request a new token and retry."
}
```

403 response Copy

```json
{
  "code": "insufficient_scope",
  "message": "The token does not have the required scope to perform this action."
}
```

## Frequently Asked Questions

### What is the default page size for Kiteworks API responses?

When no `limit` parameter is specified, the Kiteworks API returns up to 25 items per page. You can increase this up to the maximum allowed by passing a `limit` query parameter. To retrieve all results, increment the `offset` parameter by your page size until the returned count is less than your requested limit.

### Which fields can I sort on in the Kiteworks API?

Sortable fields vary by resource type. Common sort fields include `name`, `created`, `modified`, and `size`. Use the `orderBy=field:direction` format, where direction is `asc` or `desc` — for example, `orderBy=name%3Adesc`.

### What happens when I exceed the Kiteworks API rate limit?

The API returns HTTP `429 Too Many Requests` when your application exceeds the configured rate limit. The response includes a `Retry-After` header indicating how many seconds to wait before retrying. Implement exponential backoff in your client to handle this gracefully. See [Staying within limits](#rate-limiting-guidance) for a recommended retry strategy.

### What is the difference between a 401 and 403 response from the Kiteworks API?

HTTP `401 Unauthorized` means your access token is missing, malformed, or expired — you need to re-authenticate. HTTP `403 Forbidden` means your token is valid but the authenticated user or application does not have permission to perform the requested operation on the specified resource.

## Next Steps

With pagination, sorting, and error handling understood, you're ready to start building:

- [Quick Start →](quick-start.html) Make your first authenticated API call
- [API Reference →](api-reference.html) Browse all available endpoints
- [API Playground →](api-playground.html) Try pagination and sorting live in your browser