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