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

# Best Practices

> Practical guidance for Telnyx KV: naming keys, serializing values, and handling missing keys.

Practical guidance for working with KV, whether through the [`env` binding](/docs/edge-compute/kv/quick-start#path-a-the-function-binding) or the [REST API](/docs/edge-compute/kv/quick-start#path-b-the-rest-api).

## Key Naming

Keys may contain `a-z`, `A-Z`, `0-9`, and `-` `_` `/` `=` `.` (no colons). Use `/` to group related keys:

```
user/123              # User data
session/abc           # Session data
cache/api/users       # Cached API response
flag/new-feature      # Feature flag
```

Grouping by prefix also lets you enumerate a subset later — `list({ prefix: "user/" })` (or `?prefix=user/` over REST).

## Value Serialization

KV stores values verbatim, so serialize complex values yourself (no base64 needed):

```ts theme={null}
// Write
await env.MY_KV.put("user/123", JSON.stringify({ name: "Alice", age: 30 }));

// Read + parse
const user = await env.MY_KV.get<{ name: string; age: number }>("user/123", { type: "json" });
```

## Missing Keys

`get` returns `null` for a key that doesn't exist — handle it explicitly:

```ts theme={null}
const value = await env.MY_KV.get("possibly-missing-key");
if (value === null) {
    return new Response("Not found", { status: 404 });
}
```

## Keep Values Small

KV is built for many small values read on the request path, not for large blobs. A value is capped at **1 MiB** (1,048,576 bytes) — a larger write is rejected with `413`. Store big or binary objects in [Cloud Storage](/docs/cloud-storage/quick-start) and keep only the key or a small reference in KV.

## Limits

| Limit            | Value                                             |
| ---------------- | ------------------------------------------------- |
| Max value size   | 1 MiB (1,048,576 bytes) — over → `413`            |
| Max key length   | 256 characters — over → `400`                     |
| Key characters   | `a-z` `A-Z` `0-9` `-` `_` `/` `=` `.` (no colons) |
| `list` page size | `limit` 1–1000 (default 1000)                     |

## Don't Rely on Atomicity

KV has no transactions or compare-and-swap, and concurrent writers to one key are last-write-wins. Don't use it for counters, locks, or coordination — see [Consistency](/docs/edge-compute/kv/concepts/how-kv-works#consistency-and-regionality).