---
title: "Errors · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/errors
updated: 2026-10-20
licence: "All rights reserved"
---

# Errors

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

> Answer every error as RFC 9457 problem details. Give it a stable type, a plain message and the exact fields that failed.

**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/errors`.

## Required

- [Send errors as problem details](https://agentwranglers.se/playbook/api-design/errors/problem-details): Answer every error with an RFC 9457 problem details object, served as `application/problem+json`.
- [Keep error types stable](https://agentwranglers.se/playbook/api-design/errors/stable-error-types): Treat each error `type` as part of the contract. Clients branch on it, so never rename or reuse one.
- [Name every field that failed](https://agentwranglers.se/playbook/api-design/errors/validation-errors): When input fails validation, return every failing field at once, with where it is and why it failed.
- [Hide internals in errors](https://agentwranglers.se/playbook/api-design/errors/no-internal-details): Never put stack traces, queries, file paths or server versions in an error. Log them, and return a reference the client can quote.

## Recommended

- [Say when to retry](https://agentwranglers.se/playbook/api-design/errors/retry-after): For 429 and 503, send `Retry-After` so clients know how long to wait.

- Previous: [Requests and responses](https://agentwranglers.se/playbook/api-design/requests-and-responses)
- Next: [Lists](https://agentwranglers.se/playbook/api-design/lists)
- [All chapters](https://agentwranglers.se/playbook/api-design)