conductor-oss/conductor · error · IOException

Stability AI API failed with status %d: %s

Error message

Stability AI API failed with status %d: %s

What it means

Thrown by StabilityAiApi.generateImage when the v2beta image-generation endpoint returns non-2xx. IOException carries the status code and the error body string. The endpoint is selected by model name (sd3/core/ultra) and the request is multipart/form-data with Accept: image/*.

Source

Thrown at ai/src/main/java/org/conductoross/conductor/ai/providers/stabilityai/StabilityAiApi.java:129

        // Request raw image bytes with Accept: image/*
        Request request =
                new Request.Builder()
                        .url(baseUrl + endpoint)
                        .header("Authorization", "Bearer " + apiKey)
                        .header("Accept", "image/*")
                        .post(bodyBuilder.build())
                        .build();

        log.info(
                "Stability AI image generation request: endpoint={}, model={}, outputFormat={}",
                endpoint,
                params.model(),
                outputFormat);

        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                String errorBody = readResponseBody(response);
                throw new IOException(
                        "Stability AI API failed with status %d: %s"
                                .formatted(response.code(), errorBody));
            }

            ResponseBody body = response.body();
            if (body == null) {
                throw new IOException("Stability AI API returned empty response body");
            }

            // Determine the actual content type returned
            String contentType = response.header("Content-Type", "image/" + outputFormat);
            // Read the finish-reason header (e.g., SUCCESS, CONTENT_FILTERED)
            String finishReason = response.header("finish-reason", "SUCCESS");
            // Read the seed header
            String seedHeader = response.header("seed");

            byte[] imageBytes = body.bytes();
            log.info(

View on GitHub (pinned to cf7c3e4a8a)

Solutions

  1. Read the %s errorBody: Stability returns JSON with an errors array naming the field at fault.
  2. Confirm STABILITY_API_KEY is set and the account has credits (watch for 402).
  3. Validate aspect_ratio against the allowed set and seed range 0-4294967294 before calling.
  4. For 429, apply backoff; for 402, top up credits.
  5. Ensure the model name maps to the intended endpoint (sd3/core/ultra).
Defensive patterns

Strategy: try-catch

Validate before calling

if (StringUtils.isBlank(params.prompt())) {
    throw new IllegalArgumentException("Image prompt is required");
}
Set<String> validRatios = Set.of("1:1","16:9","9:16","3:2","2:3","4:5","5:4","21:9","9:21");
if (params.aspectRatio() != null && !validRatios.contains(params.aspectRatio())) {
    throw new IllegalArgumentException("Unsupported aspect_ratio: " + params.aspectRatio());
}
if (params.seed() != null && (params.seed() < 0 || params.seed() > 4294967294L)) {
    throw new IllegalArgumentException("seed must be 0-4294967294");
}

Try / catch

try {
    ImageResult img = api.generateImage(params);
} catch (IOException e) {
    String msg = e.getMessage();
    if (msg.contains("status 402")) {
        // insufficient credits - top up
    } else if (msg.contains("status 429")) {
        // rate limited - back off
    } else if (msg.contains("status 401")) {
        // bad key - do not retry
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Invalid or missing API key (401), insufficient credits (402), rate limiting (429), bad params such as an unsupported aspect_ratio/seed/out-of-range (400), content-filtered prompt (400), or a model name that resolves to an endpoint the key cannot access.

Common situations: Expired STABILITY_API_KEY, depleted credits (402 is Stability-specific), unsupported style_preset value, an aspect_ratio not in the allowed set, or a prompt tripping content moderation.

Related errors

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/7671823a1a84da2d. Report an issue: GitHub.