kernel 0.106.0__tar.gz → 0.108.0__tar.gz

kernel-0.108.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.108.0"
+}

{kernel-0.106.0 → kernel-0.108.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.108.0](https://github.com/kernel/kernel-python-sdk/compare/v0.107.0...v0.108.0) (2026-09-17)
+
+
+### Features
+
+* feat: add config registry analysis waiter ([e38c887](https://github.com/kernel/kernel-python-sdk/commit/e38c8878f9f80f5d28fce9f92df6f0a18a48e2bb))
+
+## [0.107.0](https://github.com/kernel/kernel-python-sdk/compare/v0.106.0...v0.107.0) (2026-09-16)
+
+
+### Features
+
+* Classify unevaluable config registry targets ([12ced86](https://github.com/kernel/kernel-python-sdk/commit/12ced8647c23aa43c625b288ed48c7cdf8da9125))
+* Expose persistent Browser REPL through the API ([755dba5](https://github.com/kernel/kernel-python-sdk/commit/755dba5d1273ef9083ffbc4bc7f4adf30aea2fe9))
+* Return Link spend request errors directly ([82d9f84](https://github.com/kernel/kernel-python-sdk/commit/82d9f8400a761a37debabeb79e6e5d8bec2cbe32))
+
 ## 0.106.0 (2026-09-16)
 
 Full Changelog: [v0.104.0...v0.106.0](https://github.com/kernel/kernel-python-sdk/compare/v0.104.0...v0.106.0)

{kernel-0.106.0 → kernel-0.108.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: kernel
-Version: 0.106.0
+Version: 0.108.0
 Summary: The official Python library for the kernel API
 Project-URL: Homepage, https://github.com/kernel/kernel-python-sdk
 Project-URL: Repository, https://github.com/kernel/kernel-python-sdk

{kernel-0.106.0 → kernel-0.108.0}/api.md

@@ -124,6 +124,11 @@ from kernel.types import (
     BrowserProxy,
     BrowserProxyConfig,
     BrowserProxyMode,
+    BrowserReplContent,
+    BrowserReplImageContent,
+    BrowserReplRequest,
+    BrowserReplResult,
+    BrowserReplTextContent,
     BrowserUsage,
     Profile,
     Tags,
@@ -145,6 +150,7 @@ Methods:
 - <code title="post /browsers/{id_or_name}/curl">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">curl</a>(id_or_name, \*\*<a href="src/kernel/types/browser_curl_params.py">params</a>) -> <a href="./src/kernel/types/browser_curl_response.py">BrowserCurlResponse</a></code>
 - <code title="delete /browsers/{id_or_name}">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">delete_by_id</a>(id_or_name) -> None</code>
 - <code title="post /browsers/{id_or_name}/extensions">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">load_extensions</a>(id_or_name, \*\*<a href="src/kernel/types/browser_load_extensions_params.py">params</a>) -> None</code>
+- <code title="post /browsers/{id_or_name}/repl">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">repl</a>(id_or_name, \*\*<a href="src/kernel/types/browser_repl_params.py">params</a>) -> <a href="./src/kernel/types/browser_repl_result.py">BrowserReplResult</a></code>
 
 ## Telemetry
 

{kernel-0.106.0 → kernel-0.108.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kernel"
-version = "0.106.0"
+version = "0.108.0"
 description = "The official Python library for the kernel API"
 dynamic = ["readme"]
 license = "Apache-2.0"

{kernel-0.106.0 → kernel-0.108.0}/src/kernel/_client.py

@@ -247,7 +247,6 @@ class Kernel(SyncAPIClient):
 
     @cached_property
     def browsers(self) -> BrowsersResource:
-        """Create and manage browser sessions."""
         from .resources.browsers import BrowsersResource
 
         return BrowsersResource(self)
@@ -652,7 +651,6 @@ class AsyncKernel(AsyncAPIClient):
 
     @cached_property
     def browsers(self) -> AsyncBrowsersResource:
-        """Create and manage browser sessions."""
         from .resources.browsers import AsyncBrowsersResource
 
         return AsyncBrowsersResource(self)
@@ -959,7 +957,6 @@ class KernelWithRawResponse:
 
     @cached_property
     def browsers(self) -> browsers.BrowsersResourceWithRawResponse:
-        """Create and manage browser sessions."""
         from .resources.browsers import BrowsersResourceWithRawResponse
 
         return BrowsersResourceWithRawResponse(self._client.browsers)
@@ -1098,7 +1095,6 @@ class AsyncKernelWithRawResponse:
 
     @cached_property
     def browsers(self) -> browsers.AsyncBrowsersResourceWithRawResponse:
-        """Create and manage browser sessions."""
         from .resources.browsers import AsyncBrowsersResourceWithRawResponse
 
         return AsyncBrowsersResourceWithRawResponse(self._client.browsers)
@@ -1237,7 +1233,6 @@ class KernelWithStreamedResponse:
 
     @cached_property
     def browsers(self) -> browsers.BrowsersResourceWithStreamingResponse:
-        """Create and manage browser sessions."""
         from .resources.browsers import BrowsersResourceWithStreamingResponse
 
         return BrowsersResourceWithStreamingResponse(self._client.browsers)
@@ -1376,7 +1371,6 @@ class AsyncKernelWithStreamedResponse:
 
     @cached_property
     def browsers(self) -> browsers.AsyncBrowsersResourceWithStreamingResponse:
-        """Create and manage browser sessions."""
         from .resources.browsers import AsyncBrowsersResourceWithStreamingResponse
 
         return AsyncBrowsersResourceWithStreamingResponse(self._client.browsers)

{kernel-0.106.0 → kernel-0.108.0}/src/kernel/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "kernel"
-__version__ = "0.106.0"  # x-release-please-version
+__version__ = "0.108.0"  # x-release-please-version

kernel-0.108.0/src/kernel/lib/config_registry_wait.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import math
+import time
+import random
+from datetime import datetime
+
+from .._types import Omit, Headers
+from .._exceptions import KernelError
+from ..types.config_registry_response import ConfigRegistryResponse
+
+DEFAULT_CONFIG_REGISTRY_POLL_INTERVAL = 5.0
+_TERMINAL_STATUSES = frozenset({"completed", "failed", "canceled", "expired"})
+
+
+def validate_wait_options(poll_interval: float, max_wait_seconds: float | None) -> None:
+    if not math.isfinite(poll_interval) or poll_interval <= 0:
+        raise ValueError("Expected a finite, positive value for `poll_interval`")
+    if max_wait_seconds is not None and (not math.isfinite(max_wait_seconds) or max_wait_seconds < 0):
+        raise ValueError("Expected a finite, non-negative value for `max_wait_seconds`")
+
+
+def poll_headers(extra_headers: Headers | None) -> Headers:
+    headers: dict[str, str | Omit] = dict(extra_headers or {})
+    headers["X-Stainless-Poll-Helper"] = "true"
+    return headers
+
+
+def poll_delay(poll_interval: float) -> float:
+    return poll_interval * random.uniform(0.9, 1.1)
+
+
+def wait_timeout_error(id: str, polls: int, last_status: str | None, started_at: float) -> TimeoutError:
+    elapsed = time.monotonic() - started_at
+    return TimeoutError(
+        f"Timed out waiting for config registry analysis {id!r} after {elapsed:.1f}s "
+        f"and {polls} polls; last status was {last_status!r}"
+    )
+
+
+def analysis_finished(response: ConfigRegistryResponse, requested_id: str) -> tuple[bool, str]:
+    analysis = response.analysis
+    if analysis is None:
+        raise KernelError(f"Config registry response for {requested_id!r} is missing an analysis")
+
+    analysis_id = getattr(analysis, "id", None)
+    if not isinstance(analysis_id, str) or not analysis_id:
+        raise KernelError(f"Config registry response for {requested_id!r} has no valid analysis ID")
+    if analysis_id != requested_id:
+        raise KernelError(f"Config registry response for {requested_id!r} returned analysis {analysis_id!r}")
+
+    status = getattr(analysis, "status", None)
+    if not isinstance(status, str) or not status:
+        raise KernelError(f"Config registry analysis {requested_id!r} has no valid status")
+
+    if "finished_at" not in analysis.model_fields_set:
+        raise KernelError(f"Config registry analysis {requested_id!r} is missing `finished_at`")
+
+    finished_at = getattr(analysis, "finished_at", None)
+    if finished_at is not None and not isinstance(finished_at, datetime):
+        raise KernelError(f"Config registry analysis {requested_id!r} has an invalid `finished_at`")
+
+    return finished_at is not None or status in _TERMINAL_STATUSES, status

{kernel-0.106.0 → kernel-0.108.0}/src/kernel/resources/browsers/browsers.py

@@ -36,6 +36,7 @@ from ...types import (
     BrowserMemoryRequest,
     browser_curl_params,
     browser_list_params,
+    browser_repl_params,
     browser_create_params,
     browser_update_params,
     browser_retrieve_params,
@@ -95,6 +96,7 @@ from ..._response import (
 from ...pagination import SyncOffsetPagination, AsyncOffsetPagination
 from ..._base_client import AsyncPaginator, make_request_options
 from ...types.tags_param import TagsParam
+from ...types.browser_repl_result import BrowserReplResult
 from ...types.browser_curl_response import BrowserCurlResponse
 from ...types.browser_list_response import BrowserListResponse
 from ...types.vault_reference_param import VaultReferenceParam
@@ -118,8 +120,6 @@ __all__ = ["BrowsersResource", "AsyncBrowsersResource"]
 
 
 class BrowsersResource(SyncAPIResource):
-    """Create and manage browser sessions."""
-
     @cached_property
     def telemetry(self) -> TelemetryResource:
         """
@@ -753,10 +753,75 @@ class BrowsersResource(SyncAPIResource):
             cast_to=NoneType,
         )
 
+    def repl(
+        self,
+        id_or_name: str,
+        *,
+        code: str,
+        reset: bool | Omit = omit,
+        timeout_sec: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> BrowserReplResult:
+        """
+        Execute JavaScript in a persistent Node.js runtime inside the browser VM.
+        Top-level bindings, closures, mutations, and dynamically imported modules
+        persist across calls until the REPL is reset or replaced. Start with
+        `repl.help()` to list available methods, or call `repl.help("click")` for
+        detailed help.
+
+        Expression values are ignored. Emit ordered text or image output with
+        `repl.write(...)`, console methods, or `repl.emitImage(...)`. The runtime also
+        exposes browser-control helpers, WebMCP, Patchright, Playwright, and raw CDP.
+
+        Executions are serialized. A timeout, crash, OOM, or protocol failure terminates
+        the REPL and changes its `repl_id`. This is unrestricted code execution inside
+        the browser VM and is not sandboxed.
+
+        Args:
+          code: JavaScript evaluated in a persistent Node.js runtime. Top-level bindings persist
+              until the browser VM's API process exits, the REPL is reset, or the REPL is
+              terminated after a crash or timeout. Static top-level imports are unsupported;
+              use dynamic `import()`. Expression values are ignored; emit output with
+              `repl.write(...)`, console methods, or `repl.emitImage(...)`. May be empty only
+              when `reset` is true.
+
+          reset: Terminate the current REPL, start a fresh one, and then evaluate code.
+
+          timeout_sec: Maximum execution time in seconds. Default is 60.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id_or_name:
+            raise ValueError(f"Expected a non-empty value for `id_or_name` but received {id_or_name!r}")
+        return self._post(
+            path_template("/browsers/{id_or_name}/repl", id_or_name=id_or_name),
+            body=maybe_transform(
+                {
+                    "code": code,
+                    "reset": reset,
+                    "timeout_sec": timeout_sec,
+                },
+                browser_repl_params.BrowserReplParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=BrowserReplResult,
+        )
 
-class AsyncBrowsersResource(AsyncAPIResource):
-    """Create and manage browser sessions."""
 
+class AsyncBrowsersResource(AsyncAPIResource):
     @cached_property
     def telemetry(self) -> AsyncTelemetryResource:
         """
@@ -1390,6 +1455,73 @@ class AsyncBrowsersResource(AsyncAPIResource):
             cast_to=NoneType,
         )
 
+    async def repl(
+        self,
+        id_or_name: str,
+        *,
+        code: str,
+        reset: bool | Omit = omit,
+        timeout_sec: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> BrowserReplResult:
+        """
+        Execute JavaScript in a persistent Node.js runtime inside the browser VM.
+        Top-level bindings, closures, mutations, and dynamically imported modules
+        persist across calls until the REPL is reset or replaced. Start with
+        `repl.help()` to list available methods, or call `repl.help("click")` for
+        detailed help.
+
+        Expression values are ignored. Emit ordered text or image output with
+        `repl.write(...)`, console methods, or `repl.emitImage(...)`. The runtime also
+        exposes browser-control helpers, WebMCP, Patchright, Playwright, and raw CDP.
+
+        Executions are serialized. A timeout, crash, OOM, or protocol failure terminates
+        the REPL and changes its `repl_id`. This is unrestricted code execution inside
+        the browser VM and is not sandboxed.
+
+        Args:
+          code: JavaScript evaluated in a persistent Node.js runtime. Top-level bindings persist
+              until the browser VM's API process exits, the REPL is reset, or the REPL is
+              terminated after a crash or timeout. Static top-level imports are unsupported;
+              use dynamic `import()`. Expression values are ignored; emit output with
+              `repl.write(...)`, console methods, or `repl.emitImage(...)`. May be empty only
+              when `reset` is true.
+
+          reset: Terminate the current REPL, start a fresh one, and then evaluate code.
+
+          timeout_sec: Maximum execution time in seconds. Default is 60.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id_or_name:
+            raise ValueError(f"Expected a non-empty value for `id_or_name` but received {id_or_name!r}")
+        return await self._post(
+            path_template("/browsers/{id_or_name}/repl", id_or_name=id_or_name),
+            body=await async_maybe_transform(
+                {
+                    "code": code,
+                    "reset": reset,
+                    "timeout_sec": timeout_sec,
+                },
+                browser_repl_params.BrowserReplParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=BrowserReplResult,
+        )
+
 
 class BrowsersResourceWithRawResponse:
     def __init__(self, browsers: BrowsersResource) -> None:
@@ -1416,6 +1548,9 @@ class BrowsersResourceWithRawResponse:
         self.load_extensions = to_raw_response_wrapper(
             browsers.load_extensions,
         )
+        self.repl = to_raw_response_wrapper(
+            browsers.repl,
+        )
 
     @cached_property
     def telemetry(self) -> TelemetryResourceWithRawResponse:
@@ -1485,6 +1620,9 @@ class AsyncBrowsersResourceWithRawResponse:
         self.load_extensions = async_to_raw_response_wrapper(
             browsers.load_extensions,
         )
+        self.repl = async_to_raw_response_wrapper(
+            browsers.repl,
+        )
 
     @cached_property
     def telemetry(self) -> AsyncTelemetryResourceWithRawResponse:
@@ -1554,6 +1692,9 @@ class BrowsersResourceWithStreamingResponse:
         self.load_extensions = to_streamed_response_wrapper(
             browsers.load_extensions,
         )
+        self.repl = to_streamed_response_wrapper(
+            browsers.repl,
+        )
 
     @cached_property
     def telemetry(self) -> TelemetryResourceWithStreamingResponse:
@@ -1623,6 +1764,9 @@ class AsyncBrowsersResourceWithStreamingResponse:
         self.load_extensions = async_to_streamed_response_wrapper(
             browsers.load_extensions,
         )
+        self.repl = async_to_streamed_response_wrapper(
+            browsers.repl,
+        )
 
     @cached_property
     def telemetry(self) -> AsyncTelemetryResourceWithStreamingResponse:

{kernel-0.106.0 → kernel-0.108.0}/src/kernel/resources/config_registry/analyses.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import time
+
 import httpx
 
 from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
@@ -18,6 +20,14 @@ from ...pagination import SyncOffsetPagination, AsyncOffsetPagination
 from ..._base_client import AsyncPaginator, make_request_options
 from ...types.config_registry import analysis_list_params
 from ...types.analysis_summary import AnalysisSummary
+from ...lib.config_registry_wait import (
+    DEFAULT_CONFIG_REGISTRY_POLL_INTERVAL,
+    poll_delay,
+    poll_headers,
+    analysis_finished,
+    wait_timeout_error,
+    validate_wait_options,
+)
 from ...types.config_registry_response import ConfigRegistryResponse
 
 __all__ = ["AnalysesResource", "AsyncAnalysesResource"]
@@ -79,6 +89,54 @@ class AnalysesResource(SyncAPIResource):
             cast_to=ConfigRegistryResponse,
         )
 
+    def wait_for_result(
+        self,
+        id: str,
+        *,
+        poll_interval: float = DEFAULT_CONFIG_REGISTRY_POLL_INTERVAL,
+        max_wait_seconds: float | None = None,
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> ConfigRegistryResponse:
+        """Wait for an analysis to finish and return its complete result.
+
+        The first retrieval happens immediately. ``max_wait_seconds`` is a soft
+        polling deadline: an in-flight request and its normal retries may finish
+        after it. Timing out does not cancel the remote analysis.
+        """
+        validate_wait_options(poll_interval, max_wait_seconds)
+        started_at = time.monotonic()
+        deadline = started_at + max_wait_seconds if max_wait_seconds is not None else None
+        headers = poll_headers(extra_headers)
+        polls = 0
+        last_status: str | None = None
+
+        while True:
+            if polls > 0 and deadline is not None and time.monotonic() >= deadline:
+                raise wait_timeout_error(id, polls, last_status, started_at)
+
+            response = self.retrieve(
+                id,
+                extra_headers=headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            )
+            polls += 1
+            finished, last_status = analysis_finished(response, id)
+            if finished:
+                return response
+
+            delay = poll_delay(poll_interval)
+            if deadline is not None:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise wait_timeout_error(id, polls, last_status, started_at)
+                delay = min(delay, remaining)
+            self._sleep(delay)
+
     def list(
         self,
         *,
@@ -220,6 +278,55 @@ class AsyncAnalysesResource(AsyncAPIResource):
             cast_to=ConfigRegistryResponse,
         )
 
+    async def wait_for_result(
+        self,
+        id: str,
+        *,
+        poll_interval: float = DEFAULT_CONFIG_REGISTRY_POLL_INTERVAL,
+        max_wait_seconds: float | None = None,
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> ConfigRegistryResponse:
+        """Wait for an analysis to finish and return its complete result.
+
+        The first retrieval happens immediately. ``max_wait_seconds`` is a soft
+        polling deadline: an in-flight request and its normal retries may finish
+        after it. Timing out does not cancel the remote analysis. Cancelling the
+        calling task stops the wait without cancelling the remote analysis.
+        """
+        validate_wait_options(poll_interval, max_wait_seconds)
+        started_at = time.monotonic()
+        deadline = started_at + max_wait_seconds if max_wait_seconds is not None else None
+        headers = poll_headers(extra_headers)
+        polls = 0
+        last_status: str | None = None
+
+        while True:
+            if polls > 0 and deadline is not None and time.monotonic() >= deadline:
+                raise wait_timeout_error(id, polls, last_status, started_at)
+
+            response = await self.retrieve(
+                id,
+                extra_headers=headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            )
+            polls += 1
+            finished, last_status = analysis_finished(response, id)
+            if finished:
+                return response
+
+            delay = poll_delay(poll_interval)
+            if deadline is not None:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise wait_timeout_error(id, polls, last_status, started_at)
+                delay = min(delay, remaining)
+            await self._sleep(delay)
+
     def list(
         self,
         *,

{kernel-0.106.0 → kernel-0.108.0}/src/kernel/resources/vaults/items.py

@@ -409,8 +409,10 @@ class ItemsResource(SyncAPIResource):
         device approval before native Square Pay. Keep the returned approval page open,
         poll until ready_to_submit, then submit before preparation.expires_at. Unused
         preparations expire automatically and cannot be reused. If spend-request
-        creation is rate limited, returns HTTP 429 with code
-        `spend_request_rate_limited`; stop and back off before retrying.
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
 
         Fill returns a value-free execution result. Validation failures before writing
         return 400 (invalid request or targets), 403 (access or destination denied), 404
@@ -454,8 +456,10 @@ class ItemsResource(SyncAPIResource):
         device approval before native Square Pay. Keep the returned approval page open,
         poll until ready_to_submit, then submit before preparation.expires_at. Unused
         preparations expire automatically and cannot be reused. If spend-request
-        creation is rate limited, returns HTTP 429 with code
-        `spend_request_rate_limited`; stop and back off before retrying.
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
 
         Fill returns a value-free execution result. Validation failures before writing
         return 400 (invalid request or targets), 403 (access or destination denied), 404
@@ -500,8 +504,10 @@ class ItemsResource(SyncAPIResource):
         device approval before native Square Pay. Keep the returned approval page open,
         poll until ready_to_submit, then submit before preparation.expires_at. Unused
         preparations expire automatically and cannot be reused. If spend-request
-        creation is rate limited, returns HTTP 429 with code
-        `spend_request_rate_limited`; stop and back off before retrying.
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
 
         Fill returns a value-free execution result. Validation failures before writing
         return 400 (invalid request or targets), 403 (access or destination denied), 404
@@ -555,8 +561,10 @@ class ItemsResource(SyncAPIResource):
         device approval before native Square Pay. Keep the returned approval page open,
         poll until ready_to_submit, then submit before preparation.expires_at. Unused
         preparations expire automatically and cannot be reused. If spend-request
-        creation is rate limited, returns HTTP 429 with code
-        `spend_request_rate_limited`; stop and back off before retrying.
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
 
         Fill returns a value-free execution result. Validation failures before writing
         return 400 (invalid request or targets), 403 (access or destination denied), 404
@@ -1172,8 +1180,10 @@ class AsyncItemsResource(AsyncAPIResource):
         device approval before native Square Pay. Keep the returned approval page open,
         poll until ready_to_submit, then submit before preparation.expires_at. Unused
         preparations expire automatically and cannot be reused. If spend-request
-        creation is rate limited, returns HTTP 429 with code
-        `spend_request_rate_limited`; stop and back off before retrying.
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
 
         Fill returns a value-free execution result. Validation failures before writing
         return 400 (invalid request or targets), 403 (access or destination denied), 404
@@ -1217,8 +1227,10 @@ class AsyncItemsResource(AsyncAPIResource):
         device approval before native Square Pay. Keep the returned approval page open,
         poll until ready_to_submit, then submit before preparation.expires_at. Unused
         preparations expire automatically and cannot be reused. If spend-request
-        creation is rate limited, returns HTTP 429 with code
-        `spend_request_rate_limited`; stop and back off before retrying.
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
 
         Fill returns a value-free execution result. Validation failures before writing
         return 400 (invalid request or targets), 403 (access or destination denied), 404
@@ -1263,8 +1275,10 @@ class AsyncItemsResource(AsyncAPIResource):
         device approval before native Square Pay. Keep the returned approval page open,
         poll until ready_to_submit, then submit before preparation.expires_at. Unused
         preparations expire automatically and cannot be reused. If spend-request
-        creation is rate limited, returns HTTP 429 with code
-        `spend_request_rate_limited`; stop and back off before retrying.
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
 
         Fill returns a value-free execution result. Validation failures before writing
         return 400 (invalid request or targets), 403 (access or destination denied), 404
@@ -1318,8 +1332,10 @@ class AsyncItemsResource(AsyncAPIResource):
         device approval before native Square Pay. Keep the returned approval page open,
         poll until ready_to_submit, then submit before preparation.expires_at. Unused
         preparations expire automatically and cannot be reused. If spend-request
-        creation is rate limited, returns HTTP 429 with code
-        `spend_request_rate_limited`; stop and back off before retrying.
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
 
         Fill returns a value-free execution result. Validation failures before writing
         return 400 (invalid request or targets), 403 (access or destination denied), 404