# EVS API Exception UX

> Aligning a public API's exceptions with real product behavior and AWS API standards — choosing standards-aligned errors with clear deprecation guidance over removing API surface.

Rendered version: https://codyanthony.dev/case-studies/console-ux/evs-api-exception-ux/
Author: Cody Anthony (https://codyanthony.dev/about/)

---

As Amazon EVS prepared its public API for general availability, I helped align a set of API exceptions with the behavior that actually triggered them. The work used standards-aligned exceptions and clear deprecation guidance instead of removing API surface before launch, keeping the API backward compatible through its public debut. This is one example of the upstream API work in [Design Influence and Upstream Collaboration](/case-studies/console-ux/console-api-design/).

## The challenge

A few of the API's exceptions had names that did not match the conditions that raised them. `TooManyTagsException` was returned when a customer exceeded an EVS service quota, and `TagPolicyException` was returned for invalid inputs on environment operations. The names pointed toward tags and IAM policies, while the real conditions are a service quota and input validation.

That mismatch was visible in the public reference and created a developer-experience problem: the exception name did not clearly tell developers what they needed to fix. Because public AWS APIs stay backward compatible for the life of the service, the team needed to correct the error surface before general availability without creating unnecessary friction for customers.

The team considered deprecating and removing the mismatched exceptions while the API was still pre-GA.

## Aligning the error surface with behavior

I pushed back on removing the mismatched exceptions outright because that path created backward-compatibility and customer-trust risk. Rather than choose a replacement pattern by preference, I recommended bringing the question to a senior API-design reviewer who could ground the decision in AWS standards and identify the cleanest path forward.

The review supported a standards-aligned path: introduce `ServiceQuotaExceededException` and `ValidationException`, keep the older exceptions for compatibility, and document the transition clearly. I drafted the deprecation guidance and recommended the precise term `deprecated`, since softer language would leave developers unsure whether the old exception still applied.

## What this demonstrates

- Treating an API's error surface as a developer-experience surface in its own right
- Applying AWS API design standards and backward-compatibility constraints before launch
- Using senior API-design review to ground a product decision in standards, not preference
- Writing precise deprecation guidance that tells developers exactly what changed and what to use instead
- Classifying API errors where developers are most likely to look for them

## Outcomes

Developers who hit quota or validation failures now see exceptions that accurately describe the condition they need to fix. The older exceptions remain documented with clear deprecation guidance that points to the standards-aligned replacements. The change shipped without removing API surface or delaying general availability, and the final exception model is visible in the public EVS API reference.

## Live documentation

- [ServiceQuotaExceededException](https://docs.aws.amazon.com/evs/latest/APIReference/API_ServiceQuotaExceededException.html) ([archived snapshot](https://web.archive.org/web/20260211210649/https://docs.aws.amazon.com/evs/latest/APIReference/API_ServiceQuotaExceededException.html))
- [ValidationException](https://docs.aws.amazon.com/evs/latest/APIReference/API_ValidationException.html) ([archived snapshot](https://web.archive.org/web/20260211190730/https://docs.aws.amazon.com/evs/latest/APIReference/API_ValidationException.html))
- [TooManyTagsException](https://docs.aws.amazon.com/evs/latest/APIReference/API_TooManyTagsException.html) — legacy, with deprecation guidance ([archived snapshot](https://web.archive.org/web/20260211070354/https://docs.aws.amazon.com/evs/latest/APIReference/API_TooManyTagsException.html))
- [TagPolicyException](https://docs.aws.amazon.com/evs/latest/APIReference/API_TagPolicyException.html) — legacy, with deprecation guidance ([archived snapshot](https://web.archive.org/web/20260212073015/https://docs.aws.amazon.com/evs/latest/APIReference/API_TagPolicyException.html))