1/**
2 * Anthropic error metadata augmentation.
3 *
4 * Provides Anthropic-specific metadata fields for AI error types through module
5 * augmentation, enabling typed access to Anthropic error details.
6 *
7 * @since 4.0.0
8 */
9
10/**
11 * Anthropic-specific error metadata fields.
12 *
13 * **Details**
14 *
15 * Contains the Anthropic error type and request identifier copied from provider
16 * error responses when available. Either field may be `null` when Anthropic
17 * does not include it or the response cannot be decoded.
18 *
19 * @see {@link AnthropicRateLimitMetadata} for rate-limit responses that also include parsed Anthropic rate-limit headers
20 *
21 * @category models
22 * @since 4.0.0
23 */
24export type AnthropicErrorMetadata = {
25 /**
26 * The Anthropic error type returned by the API.
27 */
28 readonly errorType: string | null
29 /**
30 * The unique request ID for debugging with Anthropic support.
31 */
32 readonly requestId: string | null
33}
34
35/**
36 * Anthropic-specific rate limit metadata fields.
37 *
38 * **Details**
39 *
40 * Extends base error metadata with rate limit-specific information from Anthropic's rate limit headers.
41 *
42 * @category models
43 * @since 4.0.0
44 */
45export type AnthropicRateLimitMetadata = AnthropicErrorMetadata & {
46 /**
47 * Number of requests allowed in the current period.
48 */
49 readonly requestsLimit: number | null
50 /**
51 * Number of requests remaining in the current period.
52 */
53 readonly requestsRemaining: number | null
54 /**
55 * Time when the request rate limit resets.
56 */
57 readonly requestsReset: string | null
58 /**
59 * Number of tokens allowed in the current period.
60 */
61 readonly tokensLimit: number | null
62 /**
63 * Number of tokens remaining in the current period.
64 */
65 readonly tokensRemaining: number | null
66 /**
67 * Time when the token rate limit resets.
68 */
69 readonly tokensReset: string | null
70}
71
72declare module "effect/ai/AiError" {
73 /**
74 * Anthropic metadata attached to `RateLimitError` values.
75 *
76 * **Details**
77 *
78 * Includes request identifiers, Anthropic error types, and parsed request or token limit headers when the provider rejects a request due to rate limits.
79 *
80 * @category models
81 * @since 4.0.0
82 */
83 export interface RateLimitErrorMetadata {
84 readonly anthropic?: AnthropicRateLimitMetadata | null
85 }
86
87 /**
88 * Anthropic metadata attached to `QuotaExhaustedError` values.
89 *
90 * **Details**
91 *
92 * Captures the Anthropic error type and request identifier for failures where the account or workspace has exhausted its available quota.
93 *
94 * @category models
95 * @since 4.0.0
96 */
97 export interface QuotaExhaustedErrorMetadata {
98 readonly anthropic?: AnthropicErrorMetadata | null
99 }
100
101 /**
102 * Anthropic metadata attached to `AuthenticationError` values.
103 *
104 * **Details**
105 *
106 * Preserves Anthropic error details for missing, invalid, or unauthorized API credentials while keeping the error in the shared AI error model.
107 *
108 * @category models
109 * @since 4.0.0
110 */
111 export interface AuthenticationErrorMetadata {
112 readonly anthropic?: AnthropicErrorMetadata | null
113 }
114
115 /**
116 * Anthropic metadata attached to `ContentPolicyError` values.
117 *
118 * **Details**
119 *
120 * Records Anthropic error details returned when a request or response is rejected by Anthropic safety or content policy enforcement.
121 *
122 * @category models
123 * @since 4.0.0
124 */
125 export interface ContentPolicyErrorMetadata {
126 readonly anthropic?: AnthropicErrorMetadata | null
127 }
128
129 /**
130 * Anthropic metadata attached to `InvalidRequestError` values.
131 *
132 * **Details**
133 *
134 * Provides the Anthropic error type and request identifier for malformed or unsupported requests rejected before model execution.
135 *
136 * @category models
137 * @since 4.0.0
138 */
139 export interface InvalidRequestErrorMetadata {
140 readonly anthropic?: AnthropicErrorMetadata | null
141 }
142
143 /**
144 * Anthropic metadata attached to `InternalProviderError` values.
145 *
146 * **Details**
147 *
148 * Preserves Anthropic request correlation data for provider-side failures that should be reported or investigated with Anthropic support.
149 *
150 * @category models
151 * @since 4.0.0
152 */
153 export interface InternalProviderErrorMetadata {
154 readonly anthropic?: AnthropicErrorMetadata | null
155 }
156
157 /**
158 * Anthropic metadata attached to `InvalidOutputError` values.
159 *
160 * **Details**
161 *
162 * Describes Anthropic-specific context for responses that could not be decoded or interpreted as valid AI output.
163 *
164 * @category models
165 * @since 4.0.0
166 */
167 export interface InvalidOutputErrorMetadata {
168 readonly anthropic?: AnthropicErrorMetadata | null
169 }
170
171 /**
172 * Anthropic metadata attached to `StructuredOutputError` values.
173 *
174 * **Details**
175 *
176 * Captures Anthropic error details for structured-output failures, including request correlation data useful when diagnosing schema-related responses.
177 *
178 * @category models
179 * @since 4.0.0
180 */
181 export interface StructuredOutputErrorMetadata {
182 readonly anthropic?: AnthropicErrorMetadata | null
183 }
184
185 /**
186 * Anthropic metadata attached to `UnsupportedSchemaError` values.
187 *
188 * **Details**
189 *
190 * Provides Anthropic error details for schemas that cannot be represented by or submitted to the Anthropic API.
191 *
192 * @category models
193 * @since 4.0.0
194 */
195 export interface UnsupportedSchemaErrorMetadata {
196 readonly anthropic?: AnthropicErrorMetadata | null
197 }
198
199 /**
200 * Anthropic metadata attached to `UnknownError` values.
201 *
202 * **Details**
203 *
204 * Retains the Anthropic error type and request identifier when a provider response cannot be classified as a more specific AI error.
205 *
206 * @category models
207 * @since 4.0.0
208 */
209 export interface UnknownErrorMetadata {
210 readonly anthropic?: AnthropicErrorMetadata | null
211 }
212}