Repository navigation
feat!: add consistent API error handling - #436
Merged
Merged
Conversation
matoous
marked this pull request as ready for review
October 23, 2026 21:29
matoous
force-pushed
the
md/error-handling
branch
from
October 23, 2026 21:44
954fd4f to
f0bc7cf
Compare
matoous
marked this pull request as draft
October 23, 2026 22:05
matoous
force-pushed
the
md/error-handling
branch
3 times, most recently
from
October 25, 2026 20:23
d20e2c8 to
b6d6e1a
Compare
This was referenced Oct 26, 2026
matoous
added a commit
to sumup/sumup-php
that referenced
this pull request
Oct 26, 2026
API exceptions now provide `getProblem(): ?Problem`, so integrations can
read Problem fields without inspecting a mixed response body.
```php
try {
$checkout = $sumup->checkouts()->get('your-checkout-id');
} catch (\SumUp\Exception\ApiException $error) {
if (($problem = $error->getProblem()) !== null) {
echo $problem->type . ': ' . $problem->detail;
}
}
```
`getResponse()` retains the original response for documented and
unexpected errors, including its headers and text. Existing body access
remains available. Problem details or titles appear in exception
messages. Incomplete or malformed Problem bodies remain available as raw
data in API errors, and Guzzle connection failures retain their original
cause.
The README shows the common error handling path beside SDK usage, with
access to the original response for other error details.
Related to sumup/sumup-py#434 and the Python
SDK changes in sumup/sumup-py#436.
matoous
force-pushed
the
md/error-handling
branch
from
October 26, 2026 20:15
b6d6e1a to
082bae1
Compare
matoous
marked this pull request as ready for review
October 26, 2026 20:16
Classify HTTP failures by status so integrations can catch authentication, permission, rate-limit, and server errors consistently across endpoints. Keep documented error details as typed bodies and preserve the original response, with decoded JSON or text for unrecognized bodies. Wrap connection failures and timeouts in SDK exceptions while retaining the original cause. Update the generator, README examples, and sync, async, and event-fetch regression coverage. BREAKING CHANGE: Documented error bodies now contain typed models or collections instead of response text. Inspect error.body directly or use error.response.text for the original text. Connection failures and timeouts now raise SDK exceptions; the original transport exception is available through error.__cause__. Refs #434.
matoous
force-pushed
the
md/error-handling
branch
from
October 26, 2026 20:18
082bae1 to
88fcd49
Compare
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
API errors currently expose response text even when the SDK promises decoded JSON. This change keeps documented error details as typed bodies and gives integrations consistent exceptions for authentication, permission, rate-limit, and server failures across endpoints, regardless of the response format.
Catch a specific failure when you need to handle it separately, or use
APIErrorto catch API response, connection, and timeout errors:HTTP 4xx and 5xx errors inherit from
APIStatusError. Theirstatusand originalresponseremain available even when the body is unrecognized or invalid JSON. Printing an error includes the HTTP status and the server's explanation when available.Inspect
error.bodyfor platform-specific details, includingProblemresponses:The same handling works with async calls and event-object fetches. Connection failures raise
APIConnectionError; timeouts raise its subclassAPITimeoutError. Both retain the request and the original exception througherror.requestanderror.__cause__.Compatibility: documented error bodies now contain typed models or collections instead of response text. Inspect
error.bodydirectly instead of callingjson.loads(error.body). Unrecognized bodies remain decoded JSON or text; useerror.response.textwhen the original HTTP response text is needed. Connection failures and timeouts now raise SDK exceptions rather than HTTPX exceptions.Closes #434.