How to handle unknown error/5xx responses

[fabio-sch]

Hello everybody,
I use orval with client react-query and axios. Also, orval generates hooks for my queries. This way I not only get typed data as well as typed errors. But I wonder, how can I handle errors like a 500 (internal server error). As far as I know, these are not part of the api documentation but may happen. As these are not part of the api documentation, orval does not generate code for that of course and the error type of that query hook consists of the known errors only.

Is there some way to extend the errors with "| unknown" for these cases? What are my options?

[pick7]

I think the cleanest solution is to model this in the OpenAPI responses if you can.

Orval's React Query + axios error type is derived from the non-2xx responses in the spec. In the current code path, the generated query error type becomes AxiosError<...> where ... is the deduped union of documented error responses. If there are no documented error responses, it falls back to unknown.

So for an expected-but-not-operation-specific failure shape, add a shared default response, or explicit 500 / 5XX responses, for example:

responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/MySuccess'
  default:
    description: Unexpected error
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ApiError'

That makes the generated TError include ApiError without needing to change each hook manually.

If the upstream spec is not under your control, the practical alternatives are:

• patch/extend the spec before running Orval, adding a default response;
• use a custom mutator and expose your own broader error type, e.g. AxiosError<KnownError | unknown> / an app-level ApiError wrapper;
• keep the generated type strict and handle truly unexpected axios errors with runtime narrowing (axios.isAxiosError(error), check error.response?.status, etc.).

I don't think there is a built-in option whose only job is to append | unknown to every generated operation error type. Orval is mostly reflecting what the OpenAPI document says can be returned.