1/**
2 * The `OpenAiError` module defines OpenAI-specific metadata that can be
3 * attached to the shared `AiError` error types used by the AI packages. It is
4 * primarily used by OpenAI-compatible clients to preserve provider details
5 * such as error codes, error types, request IDs, and rate limit headers while
6 * still exposing errors through the provider-neutral Effect AI error model.
7 *
8 * Use this module when mapping OpenAI API failures into `AiError` values and
9 * when consumers need enough structured metadata to debug failed requests,
10 * inspect quota or rate limit responses, or correlate an error with OpenAI
11 * support. The exported types are metadata shapes only; the module augmentation
12 * makes those shapes available on the corresponding shared AI error metadata
13 * interfaces without defining new runtime error classes.
14 *
15 * @since 4.0.0
16 */
17
18/**
19 * OpenAI-specific error metadata fields.
20 *
21 * @category models
22 * @since 4.0.0
23 */
24export type OpenAiErrorMetadata = {
25 /**
26 * The OpenAI error code returned by the API.
27 */
28 readonly errorCode: string | null
29 /**
30 * The OpenAI error type returned by the API.
31 */
32 readonly errorType: string | null
33 /**
34 * The unique request ID for debugging with OpenAI support.
35 */
36 readonly requestId: string | null
37}
38
39/**
40 * OpenAI-specific rate limit metadata fields.
41 *
42 * **Details**
43 *
44 * Extends base error metadata with rate limit specific information from
45 * OpenAI's rate limit headers.
46 *
47 * @category models
48 * @since 4.0.0
49 */
50export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
51 /**
52 * The rate limit type (e.g. "requests", "tokens").
53 */
54 readonly limit: string | null
55 /**
56 * Number of remaining requests in the current window.
57 */
58 readonly remaining: number | null
59 /**
60 * Time until the request rate limit resets.
61 */
62 readonly resetRequests: string | null
63 /**
64 * Time until the token rate limit resets.
65 */
66 readonly resetTokens: string | null
67}
68
69declare module "effect/ai/AiError" {
70 /**
71 * Metadata attached to rate limit errors returned by OpenAI-compatible APIs.
72 *
73 * @category models
74 * @since 4.0.0
75 */
76 export interface RateLimitErrorMetadata {
77 readonly openai?: OpenAiRateLimitMetadata | null
78 }
79
80 /**
81 * Metadata attached when an OpenAI-compatible provider reports that quota or
82 * billing limits have been exhausted.
83 *
84 * @category models
85 * @since 4.0.0
86 */
87 export interface QuotaExhaustedErrorMetadata {
88 readonly openai?: OpenAiErrorMetadata | null
89 }
90
91 /**
92 * Metadata attached to authentication failures from OpenAI-compatible APIs,
93 * such as invalid, missing, or unauthorized API credentials.
94 *
95 * @category models
96 * @since 4.0.0
97 */
98 export interface AuthenticationErrorMetadata {
99 readonly openai?: OpenAiErrorMetadata | null
100 }
101
102 /**
103 * Metadata attached when an OpenAI-compatible provider rejects content because
104 * it violates a safety or usage policy.
105 *
106 * @category models
107 * @since 4.0.0
108 */
109 export interface ContentPolicyErrorMetadata {
110 readonly openai?: OpenAiErrorMetadata | null
111 }
112
113 /**
114 * Metadata attached to malformed or unsupported requests rejected by an
115 * OpenAI-compatible API before model execution.
116 *
117 * @category models
118 * @since 4.0.0
119 */
120 export interface InvalidRequestErrorMetadata {
121 readonly openai?: OpenAiErrorMetadata | null
122 }
123
124 /**
125 * Metadata attached to unexpected server-side failures reported by an
126 * OpenAI-compatible provider.
127 *
128 * @category models
129 * @since 4.0.0
130 */
131 export interface InternalProviderErrorMetadata {
132 readonly openai?: OpenAiErrorMetadata | null
133 }
134
135 /**
136 * Metadata attached when an OpenAI-compatible response cannot be converted
137 * into the expected AI package output shape.
138 *
139 * @category models
140 * @since 4.0.0
141 */
142 export interface InvalidOutputErrorMetadata {
143 readonly openai?: OpenAiErrorMetadata | null
144 }
145
146 /**
147 * Metadata attached when an OpenAI-compatible structured output response does
148 * not satisfy the requested schema or parsing constraints.
149 *
150 * @category models
151 * @since 4.0.0
152 */
153 export interface StructuredOutputErrorMetadata {
154 readonly openai?: OpenAiErrorMetadata | null
155 }
156
157 /**
158 * Metadata attached when an OpenAI-compatible provider cannot support the
159 * schema supplied for structured output or tool definitions.
160 *
161 * @category models
162 * @since 4.0.0
163 */
164 export interface UnsupportedSchemaErrorMetadata {
165 readonly openai?: OpenAiErrorMetadata | null
166 }
167
168 /**
169 * Metadata attached when an OpenAI-compatible error response cannot be mapped
170 * to a more specific shared AI error category.
171 *
172 * @category models
173 * @since 4.0.0
174 */
175 export interface UnknownErrorMetadata {
176 readonly openai?: OpenAiErrorMetadata | null
177 }
178}