@deeprelay/sdk 0.4.1 → 0.4.3

package/docs/InferenceApi.md

@@ -86,19 +86,19 @@ example().catch(console.error);
 | **401** | Missing or invalid API key (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
 | **404** | Model or resource not found (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **409** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **409** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
 
 ## createChatCompletion
 
-> ChatCompletionResponse createChatCompletion(chatCompletionRequest, xClientRequestId)
+> ChatCompletionResponse createChatCompletion(chatCompletionRequest, xClientRequestId, xDeeprelayFallbackModels)
 
 Create a chat completion (OpenAI-compatible)
 
-OpenAI-compatible chat completion. Parameters fall into three groups:  - **Semantic parameters are gated per model.** &#x60;response_format&#x60;,   &#x60;tools&#x60;/&#x60;tool_choice&#x60;, &#x60;logprobs&#x60;/&#x60;top_logprobs&#x60; and &#x60;image_url&#x60;   content parts are sent only to a model whose &#x60;/v1/models&#x60; entry   lists the capability in &#x60;supported_parameters&#x60; (&#x60;vision&#x60; for   images). A model without it returns 400 &#x60;unsupported_parameter&#x60;   whose message names the models that do support it. When the model   supports the parameter but none of its currently routable upstreams   does, the request fails with 503 &#x60;upstream_unavailable&#x60; rather than   being silently degraded. - **Hints are forwarded or dropped, never rejected.**   &#x60;reasoning_effort&#x60;, &#x60;presence_penalty&#x60;, &#x60;frequency_penalty&#x60;, &#x60;seed&#x60;   and &#x60;parallel_tool_calls&#x60; are forwarded to an upstream that accepts   them and otherwise dropped. Every drop is reported in the   &#x60;x-deeprelay-ignored-params&#x60; response header. - **Rejected everywhere.** &#x60;logit_bias&#x60; and &#x60;function_call&#x60; return   400 &#x60;unsupported_parameter&#x60;; &#x60;input_audio&#x60; and &#x60;file&#x60; content parts   return 400 &#x60;unsupported_content_part&#x60;.  A non-strict &#x60;json_schema&#x60; sent to a model that can only guarantee JSON is served as &#x60;json_object&#x60; and reported as &#x60;response_format:downgraded&#x60;; a strict one is rejected. A &#x60;json_schema&#x60; over 64 KiB or nested deeper than 32 levels returns 400 &#x60;unsupported_parameter&#x60; (param &#x60;response_format&#x60;). An upstream rejection of a request the relay accepted returns 400 &#x60;upstream_rejected_request&#x60;. A non-chat model id returns 404 &#x60;model_not_found&#x60;. The request body is capped at 32 MiB (413 &#x60;request_too_large&#x60;).  Every successful response carries &#x60;usage.cost&#x60; and &#x60;usage.cost_details&#x60; (on a stream, only in the final usage chunk). See https://deeprelay.ai/docs/api/inference#openai-compatibility. 
+OpenAI-compatible chat completion. Parameters fall into three groups:  - **Semantic parameters are gated per model.** &#x60;response_format&#x60;,   &#x60;tools&#x60;/&#x60;tool_choice&#x60;, &#x60;logprobs&#x60;/&#x60;top_logprobs&#x60; and &#x60;image_url&#x60;   content parts are sent only to a model whose &#x60;/v1/models&#x60; entry   lists the capability in &#x60;supported_parameters&#x60; (&#x60;vision&#x60; for   images). A model without it returns 400 &#x60;unsupported_parameter&#x60;   whose message names the models that do support it. When the model   supports the parameter but none of its currently routable upstreams   does, the request fails with 503 &#x60;upstream_unavailable&#x60; rather than   being silently degraded. - **Hints are forwarded or dropped, never rejected.**   &#x60;reasoning_effort&#x60;, &#x60;presence_penalty&#x60;, &#x60;frequency_penalty&#x60;, &#x60;seed&#x60;   and &#x60;parallel_tool_calls&#x60; are forwarded to an upstream that accepts   them and otherwise dropped. Every drop is reported in the   &#x60;x-deeprelay-ignored-params&#x60; response header. - **Rejected everywhere.** &#x60;logit_bias&#x60; and &#x60;function_call&#x60; return   400 &#x60;unsupported_parameter&#x60;; &#x60;input_audio&#x60; and &#x60;file&#x60; content parts   return 400 &#x60;unsupported_content_part&#x60;.  A non-strict &#x60;json_schema&#x60; sent to a model that can only guarantee JSON is served as &#x60;json_object&#x60; and reported as &#x60;response_format:downgraded&#x60;; a strict one is rejected. A &#x60;json_schema&#x60; over 64 KiB or nested deeper than 32 levels returns 400 &#x60;unsupported_parameter&#x60; (param &#x60;response_format&#x60;). An upstream rejection of a request the relay accepted returns 400 &#x60;upstream_rejected_request&#x60;. A non-chat model id returns 404 &#x60;model_not_found&#x60;. The request body is capped at 32 MiB (413 &#x60;request_too_large&#x60;).  Every successful response carries &#x60;usage.cost&#x60; and &#x60;usage.cost_details&#x60; (on a stream, only in the final usage chunk). See https://deeprelay.ai/docs/api/inference#openai-compatibility.  **Backup models.** When the API key has &#x60;fallback_models&#x60;, or the request sends &#x60;models&#x60; or X-Deeprelay-Fallback-Models, and every provider for the requested model fails before the first token with a temporary error (unavailable, timed out, rate limited upstream, or stalled), deeprelay tries the next backup model. It never switches after the first byte, and never on a client error, a quota or budget refusal, or a content-filter result. A backup is billed at its own price under the same billing mode as the requested model. The body &#x60;model&#x60; and X-Deeprelay-Served-Model name the model that served; X-Deeprelay-Requested-Model names the one asked for, and X-Deeprelay-Fallback-Reason says why it was passed over. If no model serves, the response is the requested model\&#39;s own error, with X-Deeprelay-Fallback-Attempted. 
 
 ### Example
 
@@ -122,6 +122,8 @@ async function example() {
     chatCompletionRequest: ...,
     // string | Your own correlation id for this call, up to 128 characters. It is stored on the request-log row as `client_request_id` and can be filtered on with `GET /requests?client_request_id=`. When it is absent, an inbound `X-Request-Id` is kept in its place; the response\'s own `X-Request-Id` is always minted by deeprelay. Surrounding whitespace and control characters are removed; a longer value is dropped, never truncated. It is never used as a lookup key, so it does not need to be unique. (optional)
     xClientRequestId: xClientRequestId_example,
+    // string | Backup models for this request only, in priority order: a comma-separated list of up to 3 model ids, for example `deeprelay/glm-5.3,deeprelay/kimi-k3`. It replaces the API key\'s `fallback_models` for this request; the two lists are never merged. `none` (or an empty value) turns model fallback off for this request. If every provider for the requested model fails before the first token with a temporary error, deeprelay tries the next listed model. Each backup must still pass the key\'s model allowlist, the request\'s billing mode and the request\'s capability needs; one that does not is skipped, so this header can never widen what the key may call. More than 3 models, a malformed id, `none` mixed with ids, or this header together with a `models` body field is a 400 `invalid_request`. Not accepted by Liquid, which always serves exactly the requested model. (optional)
+    xDeeprelayFallbackModels: deeprelay/glm-5.3,deeprelay/kimi-k3,
   } satisfies CreateChatCompletionRequest;
 
   try {
@@ -143,6 +145,7 @@ example().catch(console.error);
 |------------- | ------------- | ------------- | -------------|
 | **chatCompletionRequest** | [ChatCompletionRequest](ChatCompletionRequest.md) |  | |
 | **xClientRequestId** | `string` | Your own correlation id for this call, up to 128 characters. It is stored on the request-log row as &#x60;client_request_id&#x60; and can be filtered on with &#x60;GET /requests?client_request_id&#x3D;&#x60;. When it is absent, an inbound &#x60;X-Request-Id&#x60; is kept in its place; the response\&#39;s own &#x60;X-Request-Id&#x60; is always minted by deeprelay. Surrounding whitespace and control characters are removed; a longer value is dropped, never truncated. It is never used as a lookup key, so it does not need to be unique. | [Optional] [Defaults to `undefined`] |
+| **xDeeprelayFallbackModels** | `string` | Backup models for this request only, in priority order: a comma-separated list of up to 3 model ids, for example &#x60;deeprelay/glm-5.3,deeprelay/kimi-k3&#x60;. It replaces the API key\&#39;s &#x60;fallback_models&#x60; for this request; the two lists are never merged. &#x60;none&#x60; (or an empty value) turns model fallback off for this request. If every provider for the requested model fails before the first token with a temporary error, deeprelay tries the next listed model. Each backup must still pass the key\&#39;s model allowlist, the request\&#39;s billing mode and the request\&#39;s capability needs; one that does not is skipped, so this header can never widen what the key may call. More than 3 models, a malformed id, &#x60;none&#x60; mixed with ids, or this header together with a &#x60;models&#x60; body field is a 400 &#x60;invalid_request&#x60;. Not accepted by Liquid, which always serves exactly the requested model. | [Optional] [Defaults to `undefined`] |
 
 ### Return type
 
@@ -161,17 +164,17 @@ example().catch(console.error);
 ### HTTP response details
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
-| **200** | Successful response. application/json for non-streaming requests; text/event-stream for streaming requests (stream&#x3D;true).  |  * x-deeprelay-ignored-params -  <br>  * x-deeprelay-cost -  <br>  * x-deeprelay-quota-input-remaining -  <br>  * x-deeprelay-quota-output-remaining -  <br>  * x-deeprelay-quota-reset -  <br>  * x-deeprelay-quota-weekly-input-remaining -  <br>  * x-deeprelay-quota-weekly-input-limit -  <br>  * x-deeprelay-quota-weekly-output-remaining -  <br>  * x-deeprelay-quota-weekly-output-limit -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  |
-| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
+| **200** | Successful response. application/json for non-streaming requests; text/event-stream for streaming requests (stream&#x3D;true).  |  * X-Deeprelay-Served-Model -  <br>  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Reason -  <br>  * x-deeprelay-ignored-params -  <br>  * x-deeprelay-cost -  <br>  * x-deeprelay-quota-input-remaining -  <br>  * x-deeprelay-quota-output-remaining -  <br>  * x-deeprelay-quota-reset -  <br>  * x-deeprelay-quota-weekly-input-remaining -  <br>  * x-deeprelay-quota-weekly-input-limit -  <br>  * x-deeprelay-quota-weekly-output-remaining -  <br>  * x-deeprelay-quota-weekly-output-limit -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  |
+| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **401** | Missing or invalid API key (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **402** | Insufficient balance or a spend limit reached (OpenAI error envelope, SERV-06): &#x60;insufficient_balance&#x60;, &#x60;daily_limit_reached&#x60;, &#x60;spending_limit_reached&#x60;, &#x60;api_key_budget_exceeded&#x60; (this API key\&#39;s monthly budget) or &#x60;member_spend_limit_reached&#x60; (the member\&#39;s monthly spend limit). Carries &#x60;x-should-retry: false&#x60;: the same request will not succeed until the wallet or the limit changes. |  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
 | **404** | Model or resource not found (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **413** | Request body too large (OpenAI error envelope, code request_too_large). |  * X-Deeprelay-Error-Code -  <br>  |
 | **422** | Request validation failed (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **500** | Internal server error (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **503** | No upstream could serve the request (OpenAI error envelope, &#x60;upstream_unavailable&#x60;): every capable upstream is down, shedding load, or none of the model\&#39;s routable upstreams supports a capability the request needs. Always carries Retry-After (whole seconds, rounded up) and retry-after-ms; on an overload the wait is jittered between 2 and 2.5 seconds. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **503** | No upstream could serve the request (OpenAI error envelope, &#x60;upstream_unavailable&#x60;): every capable upstream is down, shedding load, or none of the model\&#39;s routable upstreams supports a capability the request needs. Always carries Retry-After (whole seconds, rounded up) and retry-after-ms; on an overload the wait is jittered between 2 and 2.5 seconds. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
@@ -246,17 +249,17 @@ example().catch(console.error);
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
 | **200** | One embedding vector per input, in request order. |  -  |
-| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
+| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **401** | Missing or invalid API key (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **402** | Insufficient balance or a spend limit reached (OpenAI error envelope, SERV-06): &#x60;insufficient_balance&#x60;, &#x60;daily_limit_reached&#x60;, &#x60;spending_limit_reached&#x60;, &#x60;api_key_budget_exceeded&#x60; (this API key\&#39;s monthly budget) or &#x60;member_spend_limit_reached&#x60; (the member\&#39;s monthly spend limit). Carries &#x60;x-should-retry: false&#x60;: the same request will not succeed until the wallet or the limit changes. |  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
 | **404** | Model or resource not found (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **413** | Request body too large (OpenAI error envelope, code request_too_large). |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **500** | Internal server error (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **502** | The upstream answered but its response could not be used (OpenAI error envelope): code upstream_response_too_large when the vector payload exceeded the per-request size limit, or upstream_error for a malformed / misaligned response. Not retryable as-is for upstream_response_too_large — send fewer inputs. |  * X-Deeprelay-Error-Code -  <br>  |
-| **503** | No upstream could serve the request (OpenAI error envelope, &#x60;upstream_unavailable&#x60;): every capable upstream is down, shedding load, or none of the model\&#39;s routable upstreams supports a capability the request needs. Always carries Retry-After (whole seconds, rounded up) and retry-after-ms; on an overload the wait is jittered between 2 and 2.5 seconds. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * X-Deeprelay-Error-Code -  <br>  |
-| **504** | Upstream provider exceeded the synchronous per-attempt deadline (OpenAI error envelope). 504 semantic — distinct from 503 OpenAIUpstreamUnavailable which signals a connection or routing failure rather than a timeout.  |  * X-Deeprelay-Error-Code -  <br>  |
+| **502** | The upstream answered but its response could not be used (OpenAI error envelope): code upstream_response_too_large when the vector payload exceeded the per-request size limit, or upstream_error for a malformed / misaligned response. Not retryable as-is for upstream_response_too_large — send fewer inputs. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **503** | No upstream could serve the request (OpenAI error envelope, &#x60;upstream_unavailable&#x60;): every capable upstream is down, shedding load, or none of the model\&#39;s routable upstreams supports a capability the request needs. Always carries Retry-After (whole seconds, rounded up) and retry-after-ms; on an overload the wait is jittered between 2 and 2.5 seconds. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **504** | Upstream provider exceeded the synchronous per-attempt deadline (OpenAI error envelope). 504 semantic — distinct from 503 OpenAIUpstreamUnavailable which signals a connection or routing failure rather than a timeout.  |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
@@ -334,16 +337,16 @@ example().catch(console.error);
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
 | **200** | OpenAI-shaped image generation response (b64_json only). |  -  |
-| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
+| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **401** | Missing or invalid API key (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **402** | Insufficient balance or a spend limit reached (OpenAI error envelope, SERV-06): &#x60;insufficient_balance&#x60;, &#x60;daily_limit_reached&#x60;, &#x60;spending_limit_reached&#x60;, &#x60;api_key_budget_exceeded&#x60; (this API key\&#39;s monthly budget) or &#x60;member_spend_limit_reached&#x60; (the member\&#39;s monthly spend limit). Carries &#x60;x-should-retry: false&#x60;: the same request will not succeed until the wallet or the limit changes. |  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
 | **404** | Model or resource not found (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **422** | Request validation failed (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **500** | Internal server error (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **503** | No upstream could serve the request (OpenAI error envelope, &#x60;upstream_unavailable&#x60;): every capable upstream is down, shedding load, or none of the model\&#39;s routable upstreams supports a capability the request needs. Always carries Retry-After (whole seconds, rounded up) and retry-after-ms; on an overload the wait is jittered between 2 and 2.5 seconds. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * X-Deeprelay-Error-Code -  <br>  |
-| **504** | Upstream provider exceeded the synchronous per-attempt deadline (OpenAI error envelope). 504 semantic — distinct from 503 OpenAIUpstreamUnavailable which signals a connection or routing failure rather than a timeout.  |  * X-Deeprelay-Error-Code -  <br>  |
+| **503** | No upstream could serve the request (OpenAI error envelope, &#x60;upstream_unavailable&#x60;): every capable upstream is down, shedding load, or none of the model\&#39;s routable upstreams supports a capability the request needs. Always carries Retry-After (whole seconds, rounded up) and retry-after-ms; on an overload the wait is jittered between 2 and 2.5 seconds. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **504** | Upstream provider exceeded the synchronous per-attempt deadline (OpenAI error envelope). 504 semantic — distinct from 503 OpenAIUpstreamUnavailable which signals a connection or routing failure rather than a timeout.  |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
@@ -421,12 +424,12 @@ example().catch(console.error);
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
 | **200** | A video generation job object. |  -  |
-| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
+| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **401** | Missing or invalid API key (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **402** | Insufficient balance or a spend limit reached (OpenAI error envelope, SERV-06): &#x60;insufficient_balance&#x60;, &#x60;daily_limit_reached&#x60;, &#x60;spending_limit_reached&#x60;, &#x60;api_key_budget_exceeded&#x60; (this API key\&#39;s monthly budget) or &#x60;member_spend_limit_reached&#x60; (the member\&#39;s monthly spend limit). Carries &#x60;x-should-retry: false&#x60;: the same request will not succeed until the wallet or the limit changes. |  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
 | **404** | Model or resource not found (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **500** | Internal server error (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
@@ -502,7 +505,7 @@ example().catch(console.error);
 | **401** | Missing or invalid API key (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
 | **404** | Model or resource not found (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
@@ -575,7 +578,7 @@ example().catch(console.error);
 | **401** | Missing or invalid API key (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
 | **404** | Model or resource not found (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
@@ -651,7 +654,7 @@ example().catch(console.error);
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
 | **404** | Model or resource not found (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **410** | The requested artifact has expired and is no longer available (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
@@ -724,7 +727,7 @@ example().catch(console.error);
 |-------------|-------------|------------------|
 | **200** | OK |  -  |
 | **404** | Model or resource not found (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
@@ -800,10 +803,10 @@ example().catch(console.error);
 |-------------|-------------|------------------|
 | **200** | OpenAI-shaped model list. |  * Cache-Control - &#x60;public, max-age&#x3D;60&#x60; without a key; &#x60;private&#x60; with one. <br>  * ETag - Strong validator for the anonymous listing. <br>  |
 | **304** | Not modified; the If-None-Match ETag still matches. |  -  |
-| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
+| **400** | Invalid request (OpenAI error envelope). |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 | **401** | Missing or invalid API key (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
@@ -878,7 +881,7 @@ example().catch(console.error);
 | **200** | A page of video generation jobs. |  -  |
 | **401** | Missing or invalid API key (OpenAI error envelope). |  * X-Deeprelay-Error-Code -  <br>  |
 | **403** | API key lacks the required scope (&#x60;insufficient_scope&#x60;), or the key has a model allowlist that does not include the requested model (&#x60;model_not_allowed_for_key&#x60;; also the answer for a model that does not exist, so a restricted key cannot probe the catalog). OpenAI error envelope. |  * X-Deeprelay-Error-Code -  <br>  |
-| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
+| **429** | Rate limit or subscription quota exceeded (OpenAI error envelope). A per-key or per-IP rate limit (&#x60;rate_limit_exceeded&#x60;) carries Retry-After, the whole seconds to wait, rounded up (minimum 1), and retry-after-ms, the exact wait; both are the time until one request is allowed, not a full refill. A per-key denial also carries the x-ratelimit-*-requests headers. A subscription quota denial (&#x60;subscription_quota_exhausted&#x60;, raised only when the wallet cannot cover the pay-as-you-go fallback) carries &#x60;x-should-retry: false&#x60; and no Retry-After. When the tripped gate is a rolling 7-day cap (&#x60;param: weekly_input_tokens&#x60; or &#x60;param: weekly_output_tokens&#x60;), the error object also carries &#x60;quota_frees_at&#x60;, the RFC 3339 time the window frees enough capacity — the earlier of the two windows. &#x60;param&#x60; names the tripped gate: monthly_input_tokens, monthly_output_tokens, weekly_input_tokens, weekly_output_tokens, max_usage, input_overshoot (this request\&#39;s estimated input alone exceeds what is left in the tighter of the monthly and rolling 7-day input allowances), or output_overshoot (the same for the estimated output — the completion bound). On an overshoot the quota is not exhausted — send a smaller request (or a smaller max_tokens) or add credits. |  * X-Deeprelay-Requested-Model -  <br>  * X-Deeprelay-Fallback-Attempted -  <br>  * Retry-After - Seconds the client should wait before retrying. <br>  * retry-after-ms -  <br>  * x-ratelimit-limit-requests -  <br>  * x-ratelimit-remaining-requests -  <br>  * x-ratelimit-reset-requests -  <br>  * x-should-retry -  <br>  * X-Deeprelay-Error-Code -  <br>  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 

package/docs/RefereeStatus.md

@@ -8,6 +8,9 @@ Present only when the organization signed up through someone else\'s invite link
 Name | Type
 ------------ | -------------
 `status` | string
+`gate` | string
+`progressCents` | number
+`goalCents` | number
 `spentCents` | number
 `qualifySpendCents` | number
 `rewardCents` | number
@@ -23,6 +26,9 @@ import type { RefereeStatus } from '@deeprelay/sdk'
 // TODO: Update the object below with actual values
 const example = {
   "status": null,
+  "gate": null,
+  "progressCents": null,
+  "goalCents": null,
   "spentCents": null,
   "qualifySpendCents": null,
   "rewardCents": null,

package/docs/Referral.md

@@ -16,6 +16,7 @@ Name | Type
 `commissionEarnedCents` | number
 `rewardCents` | number
 `refereeRewardCents` | number
+`qualifyDepositCents` | number
 `qualifySpendCents` | number
 `holdDays` | number
 `commissionPct` | number
@@ -37,6 +38,7 @@ const example = {
   "commissionEarnedCents": null,
   "rewardCents": null,
   "refereeRewardCents": null,
+  "qualifyDepositCents": null,
   "qualifySpendCents": null,
   "holdDays": null,
   "commissionPct": null,

package/docs/RequestAttempt.md

@@ -0,0 +1,45 @@
+
+# RequestAttempt
+
+One model in a request\'s backup-model trail.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`model` | string
+`outcome` | string
+`reason` | string
+`durationMs` | number
+`ttftMs` | number
+`tries` | number
+
+## Example
+
+```typescript
+import type { RequestAttempt } from '@deeprelay/sdk'
+
+// TODO: Update the object below with actual values
+const example = {
+  "model": null,
+  "outcome": null,
+  "reason": null,
+  "durationMs": null,
+  "ttftMs": null,
+  "tries": null,
+} satisfies RequestAttempt
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as RequestAttempt
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/RequestLogEntry.md

@@ -34,6 +34,10 @@ Name | Type
 `imageCount` | number
 `videoSeconds` | number
 `suppressedCount` | number
+`requestedModel` | string
+`servedModel` | string
+`fallbackReason` | string
+`attempts` | [Array<RequestAttempt>](RequestAttempt.md)
 
 ## Example
 
@@ -69,6 +73,10 @@ const example = {
   "imageCount": null,
   "videoSeconds": null,
   "suppressedCount": null,
+  "requestedModel": null,
+  "servedModel": null,
+  "fallbackReason": null,
+  "attempts": null,
 } satisfies RequestLogEntry
 
 console.log(example)

package/docs/RequestsApi.md

@@ -12,11 +12,11 @@ All URIs are relative to *https://api.deeprelay.ai/v1*
 
 ## exportRequests
 
-> string exportRequests(key, model, surface, status, errorCode, clientRequestId, from, to)
+> string exportRequests(key, model, surface, status, errorCode, clientRequestId, from, to, fallback)
 
 Export the request log as CSV
 
-Streams every request-log row matching the filters as a CSV attachment, oldest columns first: `request_id, client_request_id, occurred_at, surface, model, key_id, key_name, key_prefix, status, http_status, error_code, finish_reason, prompt_tokens, completion_tokens, cached_tokens, reasoning_tokens, quota_units, cost, plan_covered, ttft_ms, duration_ms, ignored_params`. Takes the same filters and visibility rules as `GET /requests`, without the cursor and limit.  The export is counted before anything is written. When the filters match more rows than the export cap, the answer is 422 `export_too_large` and the problem body carries `max_rows`; narrow the time range or add a filter, then export again.  Requires the `serverless:read` scope. Exports have their own, tighter per-key rate limit. 
+Streams every request-log row matching the filters as a CSV attachment, oldest columns first: `request_id, client_request_id, occurred_at, surface, model, key_id, key_name, key_prefix, status, http_status, error_code, finish_reason, prompt_tokens, completion_tokens, cached_tokens, reasoning_tokens, quota_units, cost, plan_covered, ttft_ms, duration_ms, ignored_params, requested_model, served_model, fallback_reason`. Takes the same filters and visibility rules as `GET /requests`, without the cursor and limit.  The export is counted before anything is written. When the filters match more rows than the export cap, the answer is 422 `export_too_large` and the problem body carries `max_rows`; narrow the time range or add a filter, then export again.  Requires the `serverless:read` scope. Exports have their own, tighter per-key rate limit. 
 
 ### Example
 
@@ -52,6 +52,8 @@ async function example() {
     from: 2013-10-20T19:20:30+01:00,
     // Date | Exclusive RFC 3339 range end. Defaults to now; must be after `from`. (optional)
     to: 2013-10-20T19:20:30+01:00,
+    // boolean | `true` returns only rows a backup model served or where backups were tried (`fallback_reason` is set); `false` or absent applies no filter. Any other value is a 400. (optional)
+    fallback: true,
   } satisfies ExportRequestsRequest;
 
   try {
@@ -79,6 +81,7 @@ example().catch(console.error);
 | **clientRequestId** | `string` | Only rows whose `X-Client-Request-Id` equals this value. | [Optional] [Defaults to `undefined`] |
 | **from** | `Date` | Inclusive RFC 3339 range start. Defaults to the start of the 90-day window; an older value is clamped to it. | [Optional] [Defaults to `undefined`] |
 | **to** | `Date` | Exclusive RFC 3339 range end. Defaults to now; must be after `from`. | [Optional] [Defaults to `undefined`] |
+| **fallback** | `boolean` | `true` returns only rows a backup model served or where backups were tried (`fallback_reason` is set); `false` or absent applies no filter. Any other value is a 400. | [Optional] [Defaults to `undefined`] |
 
 ### Return type
 
@@ -182,7 +185,7 @@ example().catch(console.error);
 
 ## listRequests
 
-> RequestLogPage listRequests(key, model, surface, status, errorCode, clientRequestId, from, to, cursor, limit)
+> RequestLogPage listRequests(key, model, surface, status, errorCode, clientRequestId, from, to, fallback, cursor, limit)
 
 List requests (the request log)
 
@@ -222,6 +225,8 @@ async function example() {
     from: 2013-10-20T19:20:30+01:00,
     // Date | Exclusive RFC 3339 range end. Defaults to now; must be after `from`. (optional)
     to: 2013-10-20T19:20:30+01:00,
+    // boolean | `true` returns only rows a backup model served or where backups were tried (`fallback_reason` is set); `false` or absent applies no filter. Any other value is a 400. (optional)
+    fallback: true,
     // string (optional)
     cursor: cursor_example,
     // number | Page size. Defaults to 50; values above 100 are clamped to 100. (optional)
@@ -253,6 +258,7 @@ example().catch(console.error);
 | **clientRequestId** | `string` | Only rows whose `X-Client-Request-Id` equals this value. | [Optional] [Defaults to `undefined`] |
 | **from** | `Date` | Inclusive RFC 3339 range start. Defaults to the start of the 90-day window; an older value is clamped to it. | [Optional] [Defaults to `undefined`] |
 | **to** | `Date` | Exclusive RFC 3339 range end. Defaults to now; must be after `from`. | [Optional] [Defaults to `undefined`] |
+| **fallback** | `boolean` | `true` returns only rows a backup model served or where backups were tried (`fallback_reason` is set); `false` or absent applies no filter. Any other value is a 400. | [Optional] [Defaults to `undefined`] |
 | **cursor** | `string` |  | [Optional] [Defaults to `undefined`] |
 | **limit** | `number` | Page size. Defaults to 50; values above 100 are clamped to 100. | [Optional] [Defaults to `50`] |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeprelay/sdk",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "TypeScript SDK for the deeprelay Public Developer API",
   "author": "deeprelay Support <support@deeprelay.ai>",
   "repository": {

package/src/apis/ApiKeysApi.ts

@@ -335,7 +335,7 @@ export class ApiKeysApi extends runtime.BaseAPI {
     }
 
     /**
-     * Changes a key\'s name, budget, model allowlist, rate limit or expiry. An absent field is left unchanged; an explicit `null` clears `budget_cents`, `allowed_models` or `expires_at`. `scopes` cannot be changed after minting, and unknown fields are refused (422), so a typo never looks like a successful change. Requires the `keys:manage` capability (403 `keys_manage_required` otherwise); a member can only change keys they created. 
+     * Changes a key\'s name, budget, model allowlist, backup models, rate limit or expiry. An absent field is left unchanged; an explicit `null` clears `budget_cents`, `allowed_models`, `fallback_models` or `expires_at`. `scopes` cannot be changed after minting, and unknown fields are refused (422), so a typo never looks like a successful change. Requires the `keys:manage` capability (403 `keys_manage_required` otherwise); a member can only change keys they created. 
      * Update an API key\'s name or limits
      */
     async updateApiKeyRaw(requestParameters: UpdateApiKeyRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ApiKey>> {
@@ -346,7 +346,7 @@ export class ApiKeysApi extends runtime.BaseAPI {
     }
 
     /**
-     * Changes a key\'s name, budget, model allowlist, rate limit or expiry. An absent field is left unchanged; an explicit `null` clears `budget_cents`, `allowed_models` or `expires_at`. `scopes` cannot be changed after minting, and unknown fields are refused (422), so a typo never looks like a successful change. Requires the `keys:manage` capability (403 `keys_manage_required` otherwise); a member can only change keys they created. 
+     * Changes a key\'s name, budget, model allowlist, backup models, rate limit or expiry. An absent field is left unchanged; an explicit `null` clears `budget_cents`, `allowed_models`, `fallback_models` or `expires_at`. `scopes` cannot be changed after minting, and unknown fields are refused (422), so a typo never looks like a successful change. Requires the `keys:manage` capability (403 `keys_manage_required` otherwise); a member can only change keys they created. 
      * Update an API key\'s name or limits
      */
     async updateApiKey(requestParameters: UpdateApiKeyRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ApiKey> {

package/src/apis/BillingApi.ts

@@ -446,7 +446,7 @@ export class BillingApi extends runtime.BaseAPI {
     }
 
     /**
-     * Returns the organization\'s shareable referral code and invite link (minting the code on first read), the program terms, the referrer\'s stats, and — when this organization itself signed up through someone else\'s link — its own progress toward the referee reward. Requires the `billing:read` scope. The organization is taken from the authenticated API key, never from a parameter.  The program: share the invite link; when a friend signs up through it and spends `qualify_spend_cents` on inference, the referrer receives `reward_cents` and the friend receives `referee_reward_cents`, both as non-withdrawable credit, after a `hold_days` chargeback hold. The referrer also earns `commission_pct` percent of every real deposit the friend makes, credited as spend-only promotional credit when the deposit clears (`commission_earned_cents`). Program rewards never apply to the subscription. The terms ride on the wire so a client never hard-codes the amounts.  `referred` is ABSENT (not null) for an organization nobody referred — key on its presence. This is the same contract the dashboard\'s referral card reads. 
+     * Returns the organization\'s shareable referral code and invite link (minting the code on first read), the program terms, the referrer\'s stats, and — when this organization itself signed up through someone else\'s link — its own progress toward the referee reward. Requires the `billing:read` scope. The organization is taken from the authenticated API key, never from a parameter.  The program: share the invite link; once a friend who signed up through it has made `qualify_deposit_cents` of net real deposits (card, auto-pay or crypto, less refunds), the referrer receives `reward_cents` and the friend receives `referee_reward_cents`, both as non-withdrawable credit, after a `hold_days` chargeback hold. Both rewards are reversed if the qualifying deposit is later refunded. The deposit commission is retired and `commission_pct` is 0; when it is non-zero the referrer also earns that percent of every real deposit the friend makes. `commission_earned_cents` still reports commission earned before retirement. Program rewards never apply to the subscription. The terms ride on the wire so a client never hard-codes the amounts.  `referred` is ABSENT (not null) for an organization nobody referred — key on its presence. This is the same contract the dashboard\'s referral card reads. 
      * Get the org referral code, invite link, terms and stats
      */
     async getReferralRaw(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<Referral>> {
@@ -457,7 +457,7 @@ export class BillingApi extends runtime.BaseAPI {
     }
 
     /**
-     * Returns the organization\'s shareable referral code and invite link (minting the code on first read), the program terms, the referrer\'s stats, and — when this organization itself signed up through someone else\'s link — its own progress toward the referee reward. Requires the `billing:read` scope. The organization is taken from the authenticated API key, never from a parameter.  The program: share the invite link; when a friend signs up through it and spends `qualify_spend_cents` on inference, the referrer receives `reward_cents` and the friend receives `referee_reward_cents`, both as non-withdrawable credit, after a `hold_days` chargeback hold. The referrer also earns `commission_pct` percent of every real deposit the friend makes, credited as spend-only promotional credit when the deposit clears (`commission_earned_cents`). Program rewards never apply to the subscription. The terms ride on the wire so a client never hard-codes the amounts.  `referred` is ABSENT (not null) for an organization nobody referred — key on its presence. This is the same contract the dashboard\'s referral card reads. 
+     * Returns the organization\'s shareable referral code and invite link (minting the code on first read), the program terms, the referrer\'s stats, and — when this organization itself signed up through someone else\'s link — its own progress toward the referee reward. Requires the `billing:read` scope. The organization is taken from the authenticated API key, never from a parameter.  The program: share the invite link; once a friend who signed up through it has made `qualify_deposit_cents` of net real deposits (card, auto-pay or crypto, less refunds), the referrer receives `reward_cents` and the friend receives `referee_reward_cents`, both as non-withdrawable credit, after a `hold_days` chargeback hold. Both rewards are reversed if the qualifying deposit is later refunded. The deposit commission is retired and `commission_pct` is 0; when it is non-zero the referrer also earns that percent of every real deposit the friend makes. `commission_earned_cents` still reports commission earned before retirement. Program rewards never apply to the subscription. The terms ride on the wire so a client never hard-codes the amounts.  `referred` is ABSENT (not null) for an organization nobody referred — key on its presence. This is the same contract the dashboard\'s referral card reads. 
      * Get the org referral code, invite link, terms and stats
      */
     async getReferral(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<Referral> {

package/src/apis/InferenceApi.ts

@@ -86,6 +86,7 @@ export interface CancelVideoRequest {
 export interface CreateChatCompletionRequest {
     chatCompletionRequest: ChatCompletionRequest;
     xClientRequestId?: string;
+    xDeeprelayFallbackModels?: string;
 }
 
 export interface CreateEmbeddingsRequest {
@@ -210,6 +211,10 @@ export class InferenceApi extends runtime.BaseAPI {
             headerParameters['X-Client-Request-Id'] = String(requestParameters['xClientRequestId']);
         }
 
+        if (requestParameters['xDeeprelayFallbackModels'] != null) {
+            headerParameters['X-Deeprelay-Fallback-Models'] = String(requestParameters['xDeeprelayFallbackModels']);
+        }
+
         if (this.configuration && this.configuration.accessToken) {
             const token = this.configuration.accessToken;
             const tokenString = await token("bearerAuth", []);
@@ -231,7 +236,7 @@ export class InferenceApi extends runtime.BaseAPI {
     }
 
     /**
-     * OpenAI-compatible chat completion. Parameters fall into three groups:  - **Semantic parameters are gated per model.** `response_format`,   `tools`/`tool_choice`, `logprobs`/`top_logprobs` and `image_url`   content parts are sent only to a model whose `/v1/models` entry   lists the capability in `supported_parameters` (`vision` for   images). A model without it returns 400 `unsupported_parameter`   whose message names the models that do support it. When the model   supports the parameter but none of its currently routable upstreams   does, the request fails with 503 `upstream_unavailable` rather than   being silently degraded. - **Hints are forwarded or dropped, never rejected.**   `reasoning_effort`, `presence_penalty`, `frequency_penalty`, `seed`   and `parallel_tool_calls` are forwarded to an upstream that accepts   them and otherwise dropped. Every drop is reported in the   `x-deeprelay-ignored-params` response header. - **Rejected everywhere.** `logit_bias` and `function_call` return   400 `unsupported_parameter`; `input_audio` and `file` content parts   return 400 `unsupported_content_part`.  A non-strict `json_schema` sent to a model that can only guarantee JSON is served as `json_object` and reported as `response_format:downgraded`; a strict one is rejected. A `json_schema` over 64 KiB or nested deeper than 32 levels returns 400 `unsupported_parameter` (param `response_format`). An upstream rejection of a request the relay accepted returns 400 `upstream_rejected_request`. A non-chat model id returns 404 `model_not_found`. The request body is capped at 32 MiB (413 `request_too_large`).  Every successful response carries `usage.cost` and `usage.cost_details` (on a stream, only in the final usage chunk). See https://deeprelay.ai/docs/api/inference#openai-compatibility. 
+     * OpenAI-compatible chat completion. Parameters fall into three groups:  - **Semantic parameters are gated per model.** `response_format`,   `tools`/`tool_choice`, `logprobs`/`top_logprobs` and `image_url`   content parts are sent only to a model whose `/v1/models` entry   lists the capability in `supported_parameters` (`vision` for   images). A model without it returns 400 `unsupported_parameter`   whose message names the models that do support it. When the model   supports the parameter but none of its currently routable upstreams   does, the request fails with 503 `upstream_unavailable` rather than   being silently degraded. - **Hints are forwarded or dropped, never rejected.**   `reasoning_effort`, `presence_penalty`, `frequency_penalty`, `seed`   and `parallel_tool_calls` are forwarded to an upstream that accepts   them and otherwise dropped. Every drop is reported in the   `x-deeprelay-ignored-params` response header. - **Rejected everywhere.** `logit_bias` and `function_call` return   400 `unsupported_parameter`; `input_audio` and `file` content parts   return 400 `unsupported_content_part`.  A non-strict `json_schema` sent to a model that can only guarantee JSON is served as `json_object` and reported as `response_format:downgraded`; a strict one is rejected. A `json_schema` over 64 KiB or nested deeper than 32 levels returns 400 `unsupported_parameter` (param `response_format`). An upstream rejection of a request the relay accepted returns 400 `upstream_rejected_request`. A non-chat model id returns 404 `model_not_found`. The request body is capped at 32 MiB (413 `request_too_large`).  Every successful response carries `usage.cost` and `usage.cost_details` (on a stream, only in the final usage chunk). See https://deeprelay.ai/docs/api/inference#openai-compatibility.  **Backup models.** When the API key has `fallback_models`, or the request sends `models` or X-Deeprelay-Fallback-Models, and every provider for the requested model fails before the first token with a temporary error (unavailable, timed out, rate limited upstream, or stalled), deeprelay tries the next backup model. It never switches after the first byte, and never on a client error, a quota or budget refusal, or a content-filter result. A backup is billed at its own price under the same billing mode as the requested model. The body `model` and X-Deeprelay-Served-Model name the model that served; X-Deeprelay-Requested-Model names the one asked for, and X-Deeprelay-Fallback-Reason says why it was passed over. If no model serves, the response is the requested model\'s own error, with X-Deeprelay-Fallback-Attempted. 
      * Create a chat completion (OpenAI-compatible)
      */
     async createChatCompletionRaw(requestParameters: CreateChatCompletionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ChatCompletionResponse>> {
@@ -242,7 +247,7 @@ export class InferenceApi extends runtime.BaseAPI {
     }
 
     /**
-     * OpenAI-compatible chat completion. Parameters fall into three groups:  - **Semantic parameters are gated per model.** `response_format`,   `tools`/`tool_choice`, `logprobs`/`top_logprobs` and `image_url`   content parts are sent only to a model whose `/v1/models` entry   lists the capability in `supported_parameters` (`vision` for   images). A model without it returns 400 `unsupported_parameter`   whose message names the models that do support it. When the model   supports the parameter but none of its currently routable upstreams   does, the request fails with 503 `upstream_unavailable` rather than   being silently degraded. - **Hints are forwarded or dropped, never rejected.**   `reasoning_effort`, `presence_penalty`, `frequency_penalty`, `seed`   and `parallel_tool_calls` are forwarded to an upstream that accepts   them and otherwise dropped. Every drop is reported in the   `x-deeprelay-ignored-params` response header. - **Rejected everywhere.** `logit_bias` and `function_call` return   400 `unsupported_parameter`; `input_audio` and `file` content parts   return 400 `unsupported_content_part`.  A non-strict `json_schema` sent to a model that can only guarantee JSON is served as `json_object` and reported as `response_format:downgraded`; a strict one is rejected. A `json_schema` over 64 KiB or nested deeper than 32 levels returns 400 `unsupported_parameter` (param `response_format`). An upstream rejection of a request the relay accepted returns 400 `upstream_rejected_request`. A non-chat model id returns 404 `model_not_found`. The request body is capped at 32 MiB (413 `request_too_large`).  Every successful response carries `usage.cost` and `usage.cost_details` (on a stream, only in the final usage chunk). See https://deeprelay.ai/docs/api/inference#openai-compatibility. 
+     * OpenAI-compatible chat completion. Parameters fall into three groups:  - **Semantic parameters are gated per model.** `response_format`,   `tools`/`tool_choice`, `logprobs`/`top_logprobs` and `image_url`   content parts are sent only to a model whose `/v1/models` entry   lists the capability in `supported_parameters` (`vision` for   images). A model without it returns 400 `unsupported_parameter`   whose message names the models that do support it. When the model   supports the parameter but none of its currently routable upstreams   does, the request fails with 503 `upstream_unavailable` rather than   being silently degraded. - **Hints are forwarded or dropped, never rejected.**   `reasoning_effort`, `presence_penalty`, `frequency_penalty`, `seed`   and `parallel_tool_calls` are forwarded to an upstream that accepts   them and otherwise dropped. Every drop is reported in the   `x-deeprelay-ignored-params` response header. - **Rejected everywhere.** `logit_bias` and `function_call` return   400 `unsupported_parameter`; `input_audio` and `file` content parts   return 400 `unsupported_content_part`.  A non-strict `json_schema` sent to a model that can only guarantee JSON is served as `json_object` and reported as `response_format:downgraded`; a strict one is rejected. A `json_schema` over 64 KiB or nested deeper than 32 levels returns 400 `unsupported_parameter` (param `response_format`). An upstream rejection of a request the relay accepted returns 400 `upstream_rejected_request`. A non-chat model id returns 404 `model_not_found`. The request body is capped at 32 MiB (413 `request_too_large`).  Every successful response carries `usage.cost` and `usage.cost_details` (on a stream, only in the final usage chunk). See https://deeprelay.ai/docs/api/inference#openai-compatibility.  **Backup models.** When the API key has `fallback_models`, or the request sends `models` or X-Deeprelay-Fallback-Models, and every provider for the requested model fails before the first token with a temporary error (unavailable, timed out, rate limited upstream, or stalled), deeprelay tries the next backup model. It never switches after the first byte, and never on a client error, a quota or budget refusal, or a content-filter result. A backup is billed at its own price under the same billing mode as the requested model. The body `model` and X-Deeprelay-Served-Model name the model that served; X-Deeprelay-Requested-Model names the one asked for, and X-Deeprelay-Fallback-Reason says why it was passed over. If no model serves, the response is the requested model\'s own error, with X-Deeprelay-Fallback-Attempted. 
      * Create a chat completion (OpenAI-compatible)
      */
     async createChatCompletion(requestParameters: CreateChatCompletionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ChatCompletionResponse> {