---
title: "Tell clients to ignore what they don't · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/changes-over-time/tolerant-clients
updated: 2026-10-20
licence: "All rights reserved"
---

# Tell clients to ignore what they don't know

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Changes over time](https://agentwranglers.se/playbook/api-design/changes-over-time)
- Rule: Document that clients must ignore unknown fields and handle unknown enum values, so additions never break them.
- How: Say it in the API guide. Build your own SDKs and examples that way, and test them against responses with extra fields. Map an unknown enum value to an explicit `unknown` case instead of throwing.
- Check: An SDK test feeds a response with an extra field and a new enum value. The client keeps working.

Example:

```ts
type OrderStatus = 'pending' | 'shipped' | 'unknown'
const KNOWN_STATUSES = new Set(['pending', 'shipped'])
const toOrderStatus = (value: string): OrderStatus => (KNOWN_STATUSES.has(value) ? value as OrderStatus : 'unknown')
```

```python
from enum import Enum

class OrderStatus(Enum):
    PENDING = "pending"
    SHIPPED = "shipped"
    UNKNOWN = "unknown"

    @classmethod
    def _missing_(cls, value):
        return cls.UNKNOWN
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/changes-over-time/tolerant-clients`.

- Previous: [Announce deprecation and sunset in headers](https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers)
- Next: [Keep a changelog](https://agentwranglers.se/playbook/api-design/changes-over-time/api-changelog)
- [Changes over time](https://agentwranglers.se/playbook/api-design/changes-over-time)