Access details of the SSE Response when in error

[Pitouli]

Description

In my OpenAPI, I have an API that returns a SSE stream when successful (code 200), but returns JSON for the other status (400, 500, etc.)

Currently, when the API fails with a 400 error, I find no way to get the details of the error: the error only sends up the status of the request, but not the content, so I cannot inform my user why is request failed (in my situation, the server sends a 400 error if the uploaded file has not the correct column names)

Reproducible example or configuration

No response

OpenAPI specification (optional)

  /api/v1/documents/{domain_id}/ingest_permanent_document_batch:
    post:
      tags:
        - documents
      summary: Ingest permanent documents and link them to assistants.
      description:
        Create links between assistants and documents from the given Excel
        file. Uses Server-Sent Events (SSE) to stream progress updates.
      operationId: ingestPermanentDocumentBatch
      parameters:
        - name: domain_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Domain ID
            title: Domain Id
          description: Domain ID
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/Body_ingestPermanentDocumentBatch"
      responses:
        "200":
          description: SSE stream with progress updates
          content:
            text/event-stream:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/BatchIngestionSSEUpdate"
                  - $ref: "#/components/schemas/BatchIngestionSSEResult"
                  - $ref: "#/components/schemas/BatchIngestionSSEError"
        "400":
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationErrorResponse"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"

System information (optional)

No response

[dosubot]

Hi @Pitouli! I'm Dosu and I’m helping the openapi-ts team.

You can access the JSON error details for non-200 responses (like 400) from an SSE endpoint by using a response interceptor in the Fetch or Next.js client generated by openapi-ts. The client exposes the original response object to interceptors, so you can inspect and parse the error body before it reaches your application logic. Here’s a practical example:

import { client } from 'client/client.gen';

client.interceptors.response.use(async (response) => {
  if (!response.ok) {
    // Clone the response to avoid locking the body stream
    const errorClone = response.clone();
    try {
      const errorData = await errorClone.json();
      // You can now use errorData to inform your user
      // Optionally, attach it to the response for downstream use
      response.errorData = errorData;
    } catch (e) {
      // Handle cases where the body isn't valid JSON
      response.errorData = { message: 'Unknown error', raw: await errorClone.text() };
    }
  }
  return response;
});

Now, when you call your SSE endpoint and receive a non-200 response, you can access the parsed error details from response.errorData in your application code.

This approach works with both Fetch and Next.js clients, as both support async response interceptors and expose the full response object for inspection and modification. Note that legacy clients do not provide access to the original response, so this method won’t work there. Transformers do not process error responses, so interceptors are the recommended way to handle this scenario [Fetch client docs] [Next.js client docs].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[mrlubos]

@Pitouli do you have a proposal for improving this?

[Pitouli]

Currently, to make the SSE work, I am using the following code:

      try {
        const { stream } = await ingestPermanentDocumentBatch({
          path: {
            domain_id: domainId,
          },
          body: {
            excel_file: excelFile,
            zip_file: zipFile || null,
          },
          onSseEvent(event) {
            console.log("SSE Event:", event)
          },
          sseMaxRetryAttempts: 0,
        })

        for await (const data of stream) {
          // Loop required to consume the stream, but we handle progress in onSseEvent
          // Indeed, in this loop, we do not have access to the event name
        }
      } catch (error) {
        console.error("Error uploading documents:", error)
      } finally {
        // removed to simplify example
      }

The differences with non-SSE calls are:

• the function returns a stream,
• I have to loop over the data of the stream to initiate the call,
• the errors do not contains the response of the call but only the status code

Personally, I would have loved if calling a SSE endpoint and a non-SSE endpoint would have been identical, except that for an SSE endpoint the "onSseEvent()" callback would have been triggered on every event.

So I would have loved to write the following code:

      try {
        const result = await ingestPermanentDocumentBatch({
          path: {
            domain_id: domainId,
          },
          body: {
            excel_file: excelFile,
            zip_file: zipFile || null,
          },
          onSseEvent(event) {
            console.log("SSE Event:", event)
          },
          sseMaxRetryAttempts: 0,
        })

        // At this point, the http call is finished, and result is an object with the following properties: { data: /* what the server has returned */, request: Request; response: Response; }

      } catch (error) {
        console.error("Error uploading documents:", error)
      } finally {
        // removed to simplify example
      }

Of course, depending on the "throwOnError" option, a non-2xx response would either throw an error (caught in the catch), or simply resolve the function and we can look at result.response.ok to check if the request has been a success or not.

About result.data, it could either be the raw data that has been sent into the connection (so a text with 2 \n between each event), or perhaps more useful an array of all the parsed events (note: are there situations where a connection can me maintained for so long that keeping an array of all the events that transited through it could lead to a buffer overflow? In Chrome Devtools, the result of the call is displayed with all its events, so I suppose it is considered manageable).

And I feel like such a solution would make it easy to manage endpoints that can either return a application/json or a text/event-stream because it would be basically the same structure ; it is only the result.data that would change.

This being said, there are perhaps some subtleties about SSE that I do not know well, and that make this proposal irrelevant

[Pitouli]

You can access the JSON error details for non-200 responses (like 400) from an SSE endpoint by using a response interceptor in the Fetch or Next.js client generated by openapi-ts. The client exposes the original response object to interceptors, so you can inspect and parse the error body before it reaches your application logic.

@dosu @dosubot interesting proposition, but it seems that SSE requests do NOT trigger the interceptor.

I have added this in my root.tsx file:

client.interceptors.response.use(async (response: Response) => {
  console.log("Response received:", response)
}

I indeed see a log for every "classical" endpoint that has been called (and when the endpoint is in error, I can indeed access the detail of the error response in the response object) ; but for SSE endpoint, I see no log (not for a success SSE call nor a failed one).

So this solution is not usable as is.

(and btw @mrlubos , is it expected to not trigger the interceptor with SSE calls?)

[dosubot]

You're correct—SSE requests in openapi-ts clients do not trigger response interceptors, which matches both your experience and the current documentation (or lack thereof) for Fetch and Next.js clients. This is likely because SSE endpoints are handled via a different code path that streams data directly, bypassing the standard response pipeline where interceptors run.

As a workaround, you can check the response status before starting to process the stream. Typically, the generated client returns a stream only if the response is successful (e.g., HTTP 200). If the response is an error (like 400), the client should throw before yielding a stream, and you can catch and inspect the error in your try/catch block. If you need to access the error body, you may need to handle it at the call site, for example:

try {
  const { stream } = await ingestPermanentDocumentBatch(params);
  for await (const data of stream) {
    // handle SSE events
  }
} catch (error: any) {
  // error may contain response details for non-2xx responses
  if (error?.response) {
    const errorData = await error.response.json();
    console.error("Error details:", errorData);
  } else {
    console.error("Error uploading documents:", error);
  }
}

This approach ensures you can access error details for non-200 responses, even though interceptors aren't triggered for SSE endpoints. If you want consistent error handling between SSE and non-SSE endpoints, this pattern is currently the most robust option. There is a documentation gap here, so clarifying this behavior in the official docs would be helpful for others.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[Pitouli]

@dosu : it does not work, for two reasons :

1. SSE calls do not throw errors, whatever the value of throwOnError
2. If I apply the same logic inside the onSseError() callback function, it does not work because the error does not have a response property

[dosubot]

You're right—SSE calls in openapi-ts clients do not throw errors on non-2xx responses, regardless of the throwOnError setting, and the errors you get (including in onSseError) do not include a response property or the error body. This is because SSE endpoints are handled via a different code path that bypasses the standard response pipeline, so interceptors and typical error handling mechanisms aren't triggered for these requests. There are currently no documented hooks or workarounds to access the error response body for SSE endpoints in openapi-ts clients. This is a known limitation, so if you need to access error details for failed SSE calls, it's not currently supported by the generated client [Fetch client docs].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}