---
title: "Reject JSON with duplicate keys · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/requests-and-responses/duplicate-json-keys
id: API-92
level: Recommended
updated: 2026-10-22
build: a2a6bdfed830
tokens: 864
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Reject JSON with duplicate keys

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Requests and responses](https://agentwranglers.se/playbook/api-design/requests-and-responses.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: API-92
- Level: Recommended
- Chapter: [Requests and responses](https://agentwranglers.se/playbook/api-design/requests-and-responses.md)
- Rule: Refuse any request body in which one object holds the same key twice. Answer 400 with problem details that name the key.
- Check: A contract test sends `{"quantity": 1, "quantity": -5}` to every write endpoint. Each one answers 400 naming `quantity`, and no row changes.
- How: RFC 8259 leaves duplicate keys undefined, so parsers disagree. Many keep the last value, and others keep the first or fail. When a gateway checks `"role": "user"` and the service behind it reads `"role": "admin"`, the check is bypassed. I-JSON in RFC 7493 forbids duplicate names, so accept only I-JSON. Most standard parsers drop duplicates in silence, so turn on a strict mode or pass a hook that sees every pair. This adds to [Accept only fields you know](https://agentwranglers.se/playbook/api-design/requests-and-responses/strict-input.md). Large numbers follow [Send IDs as strings](https://agentwranglers.se/playbook/api-design/requests-and-responses/string-ids.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Python example

```python
import json

class DuplicateKey(ValueError):
    pass

def without_duplicates(pairs):
    seen = set()
    for key, _ in pairs:
        if key in seen:
            raise DuplicateKey(key)
        seen.add(key)
    return dict(pairs)

order = json.loads(body, object_pairs_hook=without_duplicates)
```

### Java example

```java
ObjectMapper mapper = JsonMapper.builder()
    .enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION)
    .build();
Order order = mapper.readValue(body, Order.class);
```

## Sources

- [RFC 7493 section 2.3 Object Constraints](https://www.rfc-editor.org/rfc/rfc7493#section-2.3)
- [RFC 8259 section 4 Objects](https://www.rfc-editor.org/rfc/rfc8259#section-4)

## Related rules

- API-12 [Accept only fields you know](https://agentwranglers.se/playbook/api-design/requests-and-responses/strict-input.md) in API design
- API-9 [Send IDs as strings](https://agentwranglers.se/playbook/api-design/requests-and-responses/string-ids.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/requests-and-responses/duplicate-json-keys">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Stream in a standard format and describe each item](https://agentwranglers.se/playbook/api-design/requests-and-responses/streamed-responses.md)
- Next: [Cap the size of every request body](https://agentwranglers.se/playbook/api-design/requests-and-responses/request-body-limit.md)
- [Requests and responses](https://agentwranglers.se/playbook/api-design/requests-and-responses.md)