# API Error Models and Problem Details
Status: public
Confidence: medium (0.865) (verified)
Last verified: 2026-06-02
Generation: ai_structured


## TL;DR

API error models define stable, machine-readable error payloads so developers and agents can distinguish validation failures, permission errors, rate limits, retries, and permanent faults.

## Core Explanation

Natural-language error messages are useful for humans, but agents need structured fields. A good error model includes a stable code, human message, affected parameter, retry guidance, request identifier, and optional problem-specific details.

For agent-facing APIs, error clarity is part of reliability. The model can recover from a precise validation error, but a vague 500 response often causes unnecessary retries or hallucinated fixes. Consistent error schemas also make SDKs, observability, and support workflows easier to automate.

## Source-Mapped Facts

- RFC 9457 defines a problem details format for carrying machine-readable details of errors in HTTP APIs. ([source](https://datatracker.ietf.org/doc/html/rfc9457))
- Google AIP-193 specifies that API errors should use the google.rpc.Status message with a canonical code, message, and details. ([source](https://google.aip.dev/193))
- Stripe API error documentation describes an error object that includes fields such as type, code, message, and param. ([source](https://docs.stripe.com/api/errors))

## Further Reading

- [RFC 9457](https://datatracker.ietf.org/doc/html/rfc9457)
- [Google AIP-193](https://google.aip.dev/193)
- [Stripe API errors](https://docs.stripe.com/api/errors)