Skip to content

feat!: add consistent API error handling - #436

Merged
matoous merged 1 commit into
mainfrom
md/error-handling
Oct 26, 2026
Merged

matoous merged 1 commit into
mainfrom
md/error-handling

Conversation

@matoous

@matoous matoous commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

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 APIError to catch API response, connection, and timeout errors:

from sumup import APIError, Sumup
from sumup.errors import APIConnectionError, AuthenticationError, RateLimitError

with Sumup() as client:
    try:
        checkout = client.checkouts.get("your-checkout-id")
    except AuthenticationError:
        print("Check your API credentials.")
    except RateLimitError:
        print("Too many requests. Try again later.")
    except APIConnectionError as error:
        print("Connection problem:", error)
    except APIError as error:
        print(error)

HTTP 4xx and 5xx errors inherit from APIStatusError. Their status and original response remain 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.body for platform-specific details, including Problem responses:

from sumup import Sumup
from sumup.errors import APIStatusError
from sumup.types import Problem

with Sumup() as client:
    try:
        checkout = client.checkouts.get("your-checkout-id")
    except APIStatusError as error:
        if isinstance(error.body, Problem):
            print(error.body.title, error.body.detail)
        else:
            print(error)

The same handling works with async calls and event-object fetches. Connection failures raise APIConnectionError; timeouts raise its subclass APITimeoutError. Both retain the request and the original exception through error.request and error.__cause__.

Compatibility: documented error bodies now contain typed models or collections instead of response text. Inspect error.body directly instead of calling json.loads(error.body). Unrecognized bodies remain decoded JSON or text; use error.response.text when the original HTTP response text is needed. Connection failures and timeouts now raise SDK exceptions rather than HTTPX exceptions.

Closes #434.

@matoous matoous self-assigned this Oct 23, 2026
@matoous
matoous marked this pull request as ready for review October 23, 2026 21:29
@matoous matoous changed the title feat!: add typed API exceptions feat!: add consistent API error handling Oct 23, 2026
@matoous
matoous marked this pull request as draft October 23, 2026 22:05
@matoous
matoous force-pushed the md/error-handling branch 3 times, most recently from d20e2c8 to b6d6e1a Compare October 25, 2026 20:23
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
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
matoous merged commit ea7023e into main Oct 26, 2026
16 checks passed
@matoous
matoous deleted the md/error-handling branch October 26, 2026 20:21
@sumup-release-bot sumup-release-bot Bot mentioned this pull request Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Question]: Should APIError.body return decoded JSON or response text?

1 participant