Agent API Error Responses and Error Models

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

API status codes, error objects, and provider error models tell agents whether to retry, ask for new input, fix authentication, or stop.

## Core Explanation

Agents that call APIs should parse error responses as structured evidence. The status code is only the first signal. Error code, message, field path, retryability, quota context, correlation ID, and documentation URL can change the recommended action.

An agent should avoid treating all 4xx responses as user mistakes or all 5xx responses as retryable. Provider-specific error models often encode precondition failures, validation details, permission problems, and safe recovery guidance.

## Source-Mapped Facts

- Stripe documentation describes API errors as returning an error object. ([source](https://docs.stripe.com/api/errors))
- The JSON:API specification defines an error object as providing additional information about problems encountered while performing an operation. ([source](https://jsonapi.org/format/#errors))
- GitHub REST API troubleshooting documentation provides guidance for common HTTP error status codes. ([source](https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api))

## Further Reading

- [Stripe API Errors](https://docs.stripe.com/api/errors)
- [JSON:API Error Objects](https://jsonapi.org/format/#errors)
- [GitHub REST API Troubleshooting](https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api)