1/**
2 * OpenAI error metadata augmentation.
3 *
4 * Provides OpenAI-specific metadata fields for AI error types through module
5 * augmentation, enabling typed access to OpenAI error details.
6 *
7 * @since 4.0.0
8 */
9
10/**
11 * OpenAI-specific error metadata fields.
12 *
13 * @category models
14 * @since 4.0.0
15 */
16export type OpenAiErrorMetadata = {
17 /**
18 * The OpenAI error code returned by the API.
19 */
20 readonly errorCode: string | null
21 /**
22 * The OpenAI error type returned by the API.
23 */
24 readonly errorType: string | null
25 /**
26 * The unique request ID for debugging with OpenAI support.
27 */
28 readonly requestId: string | null
29}
30
31/**
32 * OpenAI-specific rate limit metadata fields.
33 *
34 * **Details**
35 *
36 * Extends base error metadata with rate limit specific information from
37 * OpenAI's rate limit headers.
38 *
39 * @category models
40 * @since 4.0.0
41 */
42export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
43 /**
44 * The rate limit type (e.g. "requests", "tokens").
45 */
46 readonly limit: string | null
47 /**
48 * Number of remaining requests in the current window.
49 */
50 readonly remaining: number | null
51 /**
52 * Time until the request rate limit resets.
53 */
54 readonly resetRequests: string | null
55 /**
56 * Time until the token rate limit resets.
57 */
58 readonly resetTokens: string | null
59}
60
61declare module "effect/ai/AiError" {
62 /**
63 * OpenAI metadata attached to `RateLimitError` values.
64 *
65 * **Details**
66 *
67 * Captures OpenAI error details together with rate limit header information
68 * from responses where the provider rejected the request because a limit was
69 * reached.
70 *
71 * @category models
72 * @since 4.0.0
73 */
74 export interface RateLimitErrorMetadata {
75 /**
76 * OpenAI-specific details for the rate limit response.
77 */
78 readonly openai?: OpenAiRateLimitMetadata | null
79 }
80
81 /**
82 * OpenAI metadata attached to `QuotaExhaustedError` values.
83 *
84 * **Details**
85 *
86 * Preserves provider error details for failures caused by exhausted account,
87 * billing, or usage quota.
88 *
89 * @category models
90 * @since 4.0.0
91 */
92 export interface QuotaExhaustedErrorMetadata {
93 /**
94 * OpenAI-specific details for the quota exhaustion response.
95 */
96 readonly openai?: OpenAiErrorMetadata | null
97 }
98
99 /**
100 * OpenAI metadata attached to `AuthenticationError` values.
101 *
102 * **Details**
103 *
104 * Preserves provider error details for failed API key, authorization, or
105 * permission checks.
106 *
107 * @category models
108 * @since 4.0.0
109 */
110 export interface AuthenticationErrorMetadata {
111 /**
112 * OpenAI-specific details for the authentication failure.
113 */
114 readonly openai?: OpenAiErrorMetadata | null
115 }
116
117 /**
118 * OpenAI metadata attached to `ContentPolicyError` values.
119 *
120 * **Details**
121 *
122 * Preserves provider error details when OpenAI rejects input or output because
123 * it violates a content policy.
124 *
125 * @category models
126 * @since 4.0.0
127 */
128 export interface ContentPolicyErrorMetadata {
129 /**
130 * OpenAI-specific details for the content policy response.
131 */
132 readonly openai?: OpenAiErrorMetadata | null
133 }
134
135 /**
136 * OpenAI metadata attached to `InvalidRequestError` values.
137 *
138 * **Details**
139 *
140 * Preserves provider error details for malformed requests, unsupported
141 * parameters, or other request validation failures reported by OpenAI.
142 *
143 * @category models
144 * @since 4.0.0
145 */
146 export interface InvalidRequestErrorMetadata {
147 /**
148 * OpenAI-specific details for the invalid request response.
149 */
150 readonly openai?: OpenAiErrorMetadata | null
151 }
152
153 /**
154 * OpenAI metadata attached to `InternalProviderError` values.
155 *
156 * **Details**
157 *
158 * Preserves provider error details for OpenAI-side failures such as transient
159 * server errors.
160 *
161 * @category models
162 * @since 4.0.0
163 */
164 export interface InternalProviderErrorMetadata {
165 /**
166 * OpenAI-specific details for the internal provider response.
167 */
168 readonly openai?: OpenAiErrorMetadata | null
169 }
170
171 /**
172 * OpenAI metadata attached to `InvalidOutputError` values.
173 *
174 * **Details**
175 *
176 * Preserves provider error details when an OpenAI response cannot be parsed or
177 * validated as the expected output.
178 *
179 * @category models
180 * @since 4.0.0
181 */
182 export interface InvalidOutputErrorMetadata {
183 /**
184 * OpenAI-specific details for the invalid output response.
185 */
186 readonly openai?: OpenAiErrorMetadata | null
187 }
188
189 /**
190 * OpenAI metadata attached to `StructuredOutputError` values.
191 *
192 * **Details**
193 *
194 * Preserves provider error details when OpenAI returns content that does not
195 * satisfy the requested structured output schema.
196 *
197 * @category models
198 * @since 4.0.0
199 */
200 export interface StructuredOutputErrorMetadata {
201 /**
202 * OpenAI-specific details for the structured output failure.
203 */
204 readonly openai?: OpenAiErrorMetadata | null
205 }
206
207 /**
208 * OpenAI metadata attached to `UnsupportedSchemaError` values.
209 *
210 * **Details**
211 *
212 * Preserves provider error details when an unsupported schema failure is
213 * associated with an OpenAI response.
214 *
215 * @category models
216 * @since 4.0.0
217 */
218 export interface UnsupportedSchemaErrorMetadata {
219 /**
220 * OpenAI-specific details for the unsupported schema failure.
221 */
222 readonly openai?: OpenAiErrorMetadata | null
223 }
224
225 /**
226 * OpenAI metadata attached to `UnknownError` values.
227 *
228 * **Details**
229 *
230 * Preserves provider error details for OpenAI failures that do not map cleanly
231 * to a more specific AI error category.
232 *
233 * @category models
234 * @since 4.0.0
235 */
236 export interface UnknownErrorMetadata {
237 /**
238 * OpenAI-specific details for the unclassified provider failure.
239 */
240 readonly openai?: OpenAiErrorMetadata | null
241 }
242}