Errors in the Python SDK

Introduction

Every failure the SDK raises is the same exception, so one except covers the lot. That includes serverless invocations, which reach a different API through the same client. The client itself comes from the overview.

Catching a failure

Every failure raises a typed RunwareError with a stable code enum and the offending parameter when applicable:

from runware import Runware, RunwareError

async with Runware() as client:
    try:
        await client.run(payload)
    except RunwareError as err:
        if err.code == "quota":
            # Insufficient credits; prompt the user to top up
            ...
        elif err.code == "rateLimit":
            # Back off and retry
            ...
        elif err.code == "safety":
            # Prompt or image triggered a safety filter
            ...
        else:
            raise

The error codes

The code value is one of validation, auth, quota, rateLimit, safety, provider, timeout, notFound, serverError, connection, aborted, unknown. Raw provider-specific codes are mapped onto this stable set, so your error-handling code does not have to track upstream changes.

The same enum is used by the TypeScript SDK, so cross-language services can react to the same code values.

Serverless failures

A serverless invocation is refused through the same enum: an unknown endpoint raises notFound, an app that failed to build raises validation, and a cluster with no free capacity raises serverError. Reach for retryable rather than code when deciding whether to send the call again, since it already accounts for the difference between the two.

Errors that came from an HTTP response also carry status_code and the RFC 9457 problem_type, plus request_id, which is the one to quote in a support thread. A refusal that names a wait carries retry_after in seconds.

A task that runs and fails does not raise. It comes back with status set to "failed" and its error set, because the invocation itself succeeded. Only a failure to start raises.