Summary

Replace plain-string API error responses with machine-actionable structured errors following RFC 9457 (Problem Details for HTTP APIs). Enables agent consumers to programmatically determine retry behavior.

Motivation

From Cloudflare's RFC 9457 implementation for AI agents: when AI agents consume APIs, they need machine-readable error metadata (is this retryable? how long to wait? what category of error?). Current ApiResponse(error=<plain string>) with no structured metadata forces agents to parse error strings.

Design

Phase 1 (M7) — Core Fields

Add to error responses:

• retryable (bool) — can the request be retried?
• retry_after (int, seconds) — how long to wait before retrying
• error_code (int) — internal error code
• error_category (str enum) — auth, validation, not_found, conflict, rate_limit, budget_exhausted, provider_error, internal
• instance (str) — correlation ID from observability (near-free, already exists)

Phase 2 (M8+) — Full RFC 9457

• application/problem+json content type
• type URI linking to error documentation
• Content negotiation middleware via Accept header
• title (human summary) + detail (occurrence-specific)

Affected Files

• src/ai_company/api/errors.py (error hierarchy + category enum)
• src/ai_company/api/exception_handlers.py (structured response generation)
• src/ai_company/api/dto.py (response model update)

Research

• Cloudflare RFC 9457 Agent Error Pages
• RFC 9457 spec