# API Concepts Developer Docs

> Learn how pagination, errors, idempotency, and versioning work before you wire Mailrith into a sync flow.

## Guides
- [Pagination](https://mailrith.com/developers/pagination.md): Mailrith uses cursor pagination across list endpoints. This guide explains how to request the first page, continue with `next_cursor`, resume interrupted syncs, and reuse the same pattern across subscribers, tags, custom fields, forms, and segments.
- [Errors](https://mailrith.com/developers/errors.md): Non-2xx responses carry stable error codes and plain-language messages. This guide explains how to log errors, avoid message matching, map status codes to user or system actions, and retry only when the same request may succeed later.
- [Idempotency](https://mailrith.com/developers/idempotency.md): Import and export job creation endpoints accept idempotency keys so network retries do not queue duplicate work. This guide explains when to use a key, how to choose one, and how to store it with your own job record.
- [Versioning](https://mailrith.com/developers/versioning.md): Mailrith versions the public API in the path. This guide explains the `/v1` contract boundary, which base URLs to call, how to avoid unversioned paths, and how to compare future API versions before upgrading.