chore: update docs

Author: astahmer

README.md

@@ -207,13 +207,19 @@ await queryClient.fetchQuery(
 
 ## useMutation
 
-The mutation API supports both basic usage and advanced error handling with `withResponse` and custom transformations with `selectFn`:
+The mutation API supports both basic usage and advanced error handling with `withResponse` and custom transformations with `selectFn`. **Note**: All mutation errors are Response-like objects with type-safe error inference based on your OpenAPI error schemas.
 
 ```ts
 // Basic mutation (returns data only)
-const basicMutation = useMutation(
-  tanstackApi.mutation("post", '/authorization/organizations/:organizationId/invitations').mutationOptions
-);
+const basicMutation = useMutation({
+  ...tanstackApi.mutation("post", '/authorization/organizations/:organizationId/invitations').mutationOptions,
+  onError: (error) => {
+    // error is a Response-like object with typed data based on OpenAPI spec
+    console.log(error instanceof Response); // true
+    console.log(error.status); // 400, 401, etc. (properly typed)
+    console.log(error.data); // Typed error response body
+  }
+});
 
 // With error handling using withResponse
 const mutationWithErrorHandling = useMutation(

packages/typed-openapi/TANSTACK_QUERY_ERROR_HANDLING.md

@@ -75,9 +75,9 @@ For the above spec, the TanStack Query client generates:
 ```typescript
 // Error type is automatically inferred as:
 type CreateUserError =
-  | { status: 400; data: ValidationError }
-  | { status: 409; data: ConflictError }
-  | { status: 500; data: ServerError }
+  | Omit<Response, 'status'> & { status: 400; data: ValidationError }
+  | Omit<Response, 'status'> & { status: 409; data: ConflictError }
+  | Omit<Response, 'status'> & { status: 500; data: ServerError }
 ```
 
 ## Usage Examples
@@ -93,6 +93,9 @@ function CreateUserForm() {
     ...tanstackApi.mutation("post", "/users").mutationOptions,
     onError: (error) => {
       // error is fully typed based on your OpenAPI spec!
+      // error is also a Response instance with additional data property
+      console.log(error instanceof Response); // true
+      
       if (error.status === 400) {
         // error.data is typed as ValidationError
         console.error('Validation failed:', error.data.message);
@@ -138,6 +141,10 @@ function AdvancedCreateUserForm() {
     }).mutationOptions,
     onError: (error) => {
       // Same typed error handling as above
+      // error is also a Response instance
+      console.log(error.ok); // false
+      console.log(error.headers); // Response headers
+      
       switch (error.status) {
         case 400:
           toast.error(`Validation: ${error.data.fields.join(', ')}`);
@@ -206,13 +213,40 @@ const handleError = (error: CreateUserError) => {
 
 ## Error Structure
 
-All errors thrown by TanStack Query mutations follow this structure:
+All errors thrown by TanStack Query mutations are **Response-like objects** that extend the native Response with additional type safety:
 
 ```typescript
-interface ApiError<TData = unknown> {
-  status: number;  // HTTP status code (400-511)
+interface ApiError<TData = unknown> extends Omit<Response, 'status'> {
+  status: number;  // HTTP status code (400-511) - properly typed
   data: TData;     // Typed error response body
+  // All other Response properties are available:
+  // ok: boolean
+  // headers: Headers
+  // url: string
+  // etc.
 }
 ```
 
-This makes error handling predictable and type-safe across your entire application.
+### Key Benefits of Response-like Errors
+
+- **instanceof Response**: Error objects are proper Response instances
+- **Consistent API**: Both success and error responses follow the same Response pattern
+- **Full Response Access**: Access to headers, URL, and other Response properties
+- **Type Safety**: The `status` property is properly typed based on configured error status codes
+
+### Example Usage
+
+```typescript
+try {
+  await mutation.mutationFn(params);
+} catch (error) {
+  console.log(error instanceof Response); // true
+  console.log(error.ok); // false
+  console.log(error.status); // 400, 401, etc. (properly typed)
+  console.log(error.data); // Typed error response body
+  console.log(error.headers.get('content-type')); // Response headers
+  console.log(error.url); // Request URL
+}
+```
+
+This makes error handling predictable and type-safe across your entire application while maintaining consistency with the Response API.

packages/typed-openapi/TANSTACK_QUERY_EXAMPLES.md

@@ -128,7 +128,10 @@ function UserForm() {
       }
     },
     onError: (error) => {
-      // Type-safe error handling - error has shape { status: number, data: ErrorType }
+      // Type-safe error handling - error is a Response-like object with data property
+      console.log(error instanceof Response); // true
+      console.log(error.ok); // false
+      
       if (error.status === 400) {
         toast.error(`Validation failed: ${error.data.message}`);
       } else if (error.status === 500) {