chore(meta): rework exception handling

[iBotPeaches]

What:

• Bug Fix
• New Feature

Description:

People have been complaining about phantom issues for awhile that parsers get strings, but expect objects. This has been reported a lot of times.

Folks have tried to fix this many times by either overhauling exceptions, detecting http status codes, introducing many new exceptions and all of this is not addressing the root problem.

A long time ago an issue was created to support audio transcription api (#59) and that endpoint has a powerhouse of a feature.

Select the format of the output, in one of these options: json, text, srt, verbose_json, or vtt

The endpoint can change its return to a variety of types. So base Response classes were adapted to support string/array to handle all of those. The problem however that every single other endpoint only supports json/array. So now that the base class supports a string (the other types) they can crash in odd situations - like when get an internal error (string) that is then expected to be handled by every single entity, when only Audio is prepped for it.

You'll probably get a 404 not found in pure text from some OpenAI load balancer at some point. At thousands of OpenAI calls a day we get roughly 0-3 of these errors every single day. Its an ugly error - its not a structured OpenAI return. Since the base classes support strings after #59 - it moves onward to any other non-audio class and crashes. This exception is ugly

Argument #1 ($contents) must be of type array, string given

Been reported for years. So I'm on a journey to resolve this at the root.

Steps

• Remove string as a valid type for Base Response
• Introduce Audio Base Response (string/array)
• Augment real life tests in my test repo for all different formats for audio/transcription to prevent regressions (iBotPeaches/openai-php-laravel-test@a9be887)
• Add ResponseInterface to exceptions to catch raw response easier
• Correct Audio class with all these changes
• Tests for sampled 404 issue
• Tests for Response included in exceptions
• Capture unknown headers in a new meta class
• (Stretch) Add a PSR-18 Laravel HTTP/Client implementation into Laravel repo to aid in tracing these calls.

Related:

fixes #326
fixes #339
fixes #341
fixes #402
fixes #549

closes #553
closes #440
closes #429
closes #359

[iBotPeaches]

thanks @bytestream! pinged a few coworkers to double check the work as well.

[bytestream]

@iBotPeaches I've just noticed that you can't access the headers on rate limited requests? I think $response needs to be included in the throw new ErrorException calls - like you did in the other cases

[iBotPeaches]

@iBotPeaches I've just noticed that you can't access the headers on rate limited requests? I think $response needs to be included in the throw new ErrorException calls - like you did in the other cases

good catch. I'll do that today/tomorrow