@@ -1,6 +1,8 @@
 package com.dbaagent.llm.api;
 
+import java.time.Duration;
 import java.util.List;
+import java.util.Optional;
 
 public interface LlmEmbeddingProvider {
 
@@ -19,4 +21,27 @@ public interface LlmEmbeddingProvider {
     int dimensions(LlmCredentials credentials);
 
     LlmErrorCategory classify(Throwable throwable);
+
+    /**
+     * How long the provider asked us to wait before retrying, when it said so.
+     *
+     * <p>{@link #classify} answers <em>whether</em> a retry is worth attempting;
+     * this answers <em>when</em>. They are separate questions and only the provider
+     * can answer the second: the delay arrives in a transport header or an error
+     * string whose shape is vendor-specific.
+     *
+     * <p>Without it, a rate-limited caller backs off on a schedule it invented.
+     * Observed against Azure OpenAI on an S0 tier: the service replied 429
+     * "retry after 4 seconds" while the local policy slept 750ms then 1500ms, so
+     * every attempt landed inside the cooldown and the work was dropped as
+     * "transient". Retrying sooner than asked does not just waste the attempt —
+     * it is also what the rate limiter is counting.
+     *
+     * <p>Empty means no opinion; the caller keeps its own schedule. Callers must
+     * treat a returned value as untrusted input and cap it: it is a number from a
+     * remote server, and honouring an arbitrarily large one would hang the thread.
+     */
+    default Optional<Duration> retryAfter(Throwable throwable) {
+        return Optional.empty();
+    }
 }
@@ -15,6 +15,7 @@
 import com.openai.models.embeddings.Embedding;
 import com.openai.models.embeddings.EmbeddingCreateParams;
 import com.openai.models.embeddings.EmbeddingModel;
+import com.openai.errors.OpenAIServiceException;
 
 import java.io.IOException;
 import java.nio.channels.UnresolvedAddressException;
@@ -24,9 +25,12 @@
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Optional;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.function.Function;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Component;
@@ -55,6 +59,25 @@ public class OpenAiCompatibleEmbeddingProvider implements LlmEmbeddingProvider {
     private static final String DEFAULT_MODEL = "text-embedding-3-large";
     private static final String DEFAULT_ENDPOINT = "https://api.openai.com/v1";
 
+    /**
+     * Header names carrying a retry delay in <em>seconds</em>. Both casings are listed
+     * because the SDK's {@code Headers.values} lookup is not documented as
+     * case-insensitive and the wire casing varies between OpenAI and Azure gateways.
+     *
+     * <p>{@code retry-after-ms} is excluded on purpose: it is millisecond-valued, and
+     * {@link #parseSeconds} would read it as seconds and sleep a thousandfold too long.
+     */
+    private static final List<String> RETRY_AFTER_HEADERS = List.of("Retry-After", "retry-after");
+
+    /**
+     * Matches the delay stated in an error body: "retry after 4 seconds",
+     * "try again in 1.5s". Anchored on the verb phrase rather than a bare number so it
+     * cannot pick up an unrelated figure elsewhere in the message.
+     */
+    private static final Pattern RETRY_AFTER_PROSE = Pattern.compile(
+            "(?:retry after|try again in)\\s+([0-9]+(?:\\.[0-9]+)?)\\s*(?:s\\b|sec|second)",
+            Pattern.CASE_INSENSITIVE);
+
     private static final LlmProviderDescriptor DESCRIPTOR = new LlmProviderDescriptor(
             "openai",
             Set.of("azure", "azure-openai"),
@@ -271,4 +294,86 @@ public LlmErrorCategory classify(Throwable throwable) {
         }
         return LlmErrorCategory.UNKNOWN;
     }
+
+    /**
+     * Prefers the {@code Retry-After} header, falling back to the delay the service
+     * states in prose.
+     *
+     * <p>The header is authoritative and standard. The prose fallback exists because
+     * Azure OpenAI states the number in the 429 body, and the body reaches us on
+     * paths where the header did not survive the SDK's error mapping. Both forms
+     * seen in the wild:
+     *
+     * <pre>
+     *   Azure:  "Please retry after 4 seconds."
+     *   OpenAI: "Please try again in 1.5s."
+     * </pre>
+     *
+     * <p>Deliberately NOT folded into {@link #classify}: that method returns a
+     * category shared by every provider, this returns a vendor-specific number.
+     */
+    @Override
+    public Optional<Duration> retryAfter(Throwable throwable) {
+        for (Throwable t = throwable; t != null; t = t.getCause()) {
+            if (t instanceof OpenAIServiceException serviceException) {
+                Optional<Duration> fromHeader = headerRetryAfter(serviceException);
+                if (fromHeader.isPresent()) {
+                    return fromHeader;
+                }
+            }
+            Optional<Duration> fromMessage = messageRetryAfter(t.getMessage());
+            if (fromMessage.isPresent()) {
+                return fromMessage;
+            }
+        }
+        return Optional.empty();
+    }
+
+    /**
+     * RFC 9110 allows {@code Retry-After} to be delta-seconds or an HTTP date. Only
+     * the numeric form is honoured: the date form would require trusting the remote
+     * clock against ours, and no OpenAI-compatible service has been seen to send it.
+     */
+    private Optional<Duration> headerRetryAfter(OpenAIServiceException exception) {
+        for (String name : RETRY_AFTER_HEADERS) {
+            List<String> values;
+            try {
+                values = exception.headers().values(name);
+            } catch (RuntimeException ignored) {
+                // A malformed error response must never mask the original failure.
+                continue;
+            }
+            for (String value : values) {
+                Optional<Duration> parsed = parseSeconds(value);
+                if (parsed.isPresent()) {
+                    return parsed;
+                }
+            }
+        }
+        return Optional.empty();
+    }
+
+    private Optional<Duration> messageRetryAfter(String message) {
+        if (message == null) {
+            return Optional.empty();
+        }
+        Matcher matcher = RETRY_AFTER_PROSE.matcher(message);
+        return matcher.find() ? parseSeconds(matcher.group(1)) : Optional.empty();
+    }
+
+    /** Rejects negatives and non-numbers; zero is a real answer ("retry immediately"). */
+    private Optional<Duration> parseSeconds(String raw) {
+        if (raw == null || raw.isBlank()) {
+            return Optional.empty();
+        }
+        try {
+            double seconds = Double.parseDouble(raw.trim());
+            if (seconds < 0 || !Double.isFinite(seconds)) {
+                return Optional.empty();
+            }
+            return Optional.of(Duration.ofMillis(Math.round(seconds * 1000)));
+        } catch (NumberFormatException e) {
+            return Optional.empty();
+        }
+    }
 }
@@ -26,6 +26,7 @@
 import java.nio.charset.StandardCharsets;
 import java.time.Duration;
 import java.util.List;
+import java.util.concurrent.ThreadLocalRandom;
 
 /**
  * Spring AI ChatModel implementation for OpenAI and every OpenAI-compatible endpoint:
@@ -56,6 +57,25 @@ public class ResponsesApiChatModel implements ChatModel {
     private static final int MAX_RETRIES = 3;
     private static final long INITIAL_BACKOFF_MS = 2000;
 
+    /**
+     * Upper bound on a backoff wait, including any {@code Retry-After} the service sends.
+     * The request timeout is 8 minutes, so a long sleep here holds a request thread and
+     * the user's browser open; 30s keeps a retry a hiccup rather than a hang.
+     */
+    private static final long MAX_BACKOFF_MS = 30_000;
+
+    /**
+     * Fraction of the computed backoff that is fixed; the rest is randomised.
+     *
+     * <p>The agent issues several model calls in parallel. When a burst limit rejects
+     * them together, a purely deterministic backoff wakes every one of them at the same
+     * instant and they collide again — the retries recreate the burst they are backing
+     * off from. Observed against an Azure deployment that served 8 sequential requests
+     * without complaint and rejected 6 concurrent ones. Randomising part of the wait
+     * spreads the retries out.
+     */
+    private static final double BACKOFF_JITTER_FRACTION = 0.5;
+
     public ResponsesApiChatModel(String endpoint, String apiKey, String model,
                                   String apiVersion, double temperature, boolean useResponsesApi) {
         this.useResponsesApi = useResponsesApi;
@@ -101,6 +121,47 @@ HttpRequest buildHttpRequest(String body, Duration timeout) {
                 .build();
     }
 
+    /**
+     * How long to wait before the next attempt: exponential, part-randomised, floored by
+     * whatever the service asked for, and capped.
+     *
+     * <p>Package-private so the retry policy can be asserted without making real calls.
+     *
+     * @param attempt          zero-based attempt index that just failed
+     * @param retryAfterMillis the service's own instruction, or 0 when it gave none
+     */
+    static long backoffMillis(int attempt, long retryAfterMillis) {
+        long exponential = INITIAL_BACKOFF_MS * (1L << attempt);
+        long fixed = (long) (exponential * (1 - BACKOFF_JITTER_FRACTION));
+        long jittered = fixed + (long) (ThreadLocalRandom.current().nextDouble()
+                * (exponential - fixed));
+        // The service's instruction is a floor, not a replacement: it says "not before
+        // this", and our own schedule may already be waiting longer than that.
+        long wait = Math.max(jittered, Math.max(retryAfterMillis, 0));
+        return Math.min(wait, MAX_BACKOFF_MS);
+    }
+
+    /**
+     * The {@code Retry-After} delay in milliseconds, or 0 when absent or unparseable.
+     *
+     * <p>Only RFC 9110's delta-seconds form is read; the HTTP-date form would mean
+     * trusting the remote clock against ours. A malformed header degrades to "no
+     * instruction" rather than throwing — a bad header must not turn a retryable
+     * response into a hard failure.
+     */
+    private static long retryAfterMillis(HttpResponse<?> response) {
+        return response.headers().firstValue("retry-after")
+                .map(value -> {
+                    try {
+                        double seconds = Double.parseDouble(value.trim());
+                        return seconds >= 0 ? Math.round(seconds * 1000) : 0L;
+                    } catch (NumberFormatException e) {
+                        return 0L;
+                    }
+                })
+                .orElse(0L);
+    }
+
     static String resolveApiUrl(String endpoint, String model, String apiVersion, boolean useResponsesApi) {
         String base = endpoint.endsWith("/") ? endpoint.substring(0, endpoint.length() - 1) : endpoint;
         boolean isOpenAiCompatible = isOpenAiCompatibleEndpoint(base);
@@ -142,7 +203,7 @@ public ChatResponse call(Prompt prompt) {
                 HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
 
                 if (isRetryableStatus(response.statusCode()) && attempt < MAX_RETRIES) {
-                    long backoff = INITIAL_BACKOFF_MS * (1L << attempt);
+                    long backoff = backoffMillis(attempt, retryAfterMillis(response));
                     log.warn("Chat provider returned {} (attempt {}/{}), retrying in {}ms",
                             response.statusCode(), attempt + 1, MAX_RETRIES, backoff);
                     Thread.sleep(backoff);
@@ -328,7 +389,7 @@ private void streamResponse(String body, FluxSink<ChatResponse> sink) {
                         httpClient.send(request, HttpResponse.BodyHandlers.ofInputStream());
 
                 if (isRetryableStatus(response.statusCode()) && attempt < MAX_RETRIES) {
-                    long backoff = INITIAL_BACKOFF_MS * (1L << attempt);
+                    long backoff = backoffMillis(attempt, retryAfterMillis(response));
                     log.warn("Chat provider stream returned {} (attempt {}/{}), retrying in {}ms",
                             response.statusCode(), attempt + 1, MAX_RETRIES, backoff);
                     response.body().close();
 
@@ -11,6 +11,7 @@
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Service;
 
+import java.time.Duration;
 import java.util.Collections;
 import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
@@ -32,12 +33,22 @@ public class EmbeddingService {
     private static final int MAX_RETRY_ATTEMPTS = 2;
     private static final long RETRY_BACKOFF_MS = 750L;
 
+    /**
+     * Ceiling on a provider-supplied {@code Retry-After}. Brain init embeds documents on
+     * a bounded worker pool, so a long sleep here stalls the whole stage; 30s is longer
+     * than any real rate-limit cooldown observed and short enough to stay a hiccup.
+     */
+    private static final Duration MAX_RETRY_AFTER = Duration.ofSeconds(30);
+
     private final LlmConfigResolver resolver;
     private final LlmProviderRegistry registry;
     private final int maxChars;
     private final boolean failOpen;
     private final long retryBackoffMs;
 
+    /** Ceiling applied to a provider-supplied {@code Retry-After}. See {@link #MAX_RETRY_AFTER}. */
+    private final Duration maxRetryAfter;
+
     /**
      * Memoised vector widths, keyed by the non-secret credential signature. Bounded in
      * practice by the number of distinct provider/endpoint/model combinations an operator
@@ -58,11 +69,22 @@ public EmbeddingService(
     /** Test seam: lets the retry tests run with no real sleeping. */
     EmbeddingService(LlmConfigResolver resolver, LlmProviderRegistry registry,
                      int maxChars, boolean failOpen, long retryBackoffMs) {
+        this(resolver, registry, maxChars, failOpen, retryBackoffMs, MAX_RETRY_AFTER);
+    }
+
+    /**
+     * Test seam: also lowers the {@code Retry-After} ceiling, so the cap can be asserted
+     * without a test that actually sleeps for it.
+     */
+    EmbeddingService(LlmConfigResolver resolver, LlmProviderRegistry registry,
+                     int maxChars, boolean failOpen, long retryBackoffMs,
+                     Duration maxRetryAfter) {
         this.resolver = resolver;
         this.registry = registry;
         this.maxChars = maxChars;
         this.failOpen = failOpen;
         this.retryBackoffMs = retryBackoffMs;
+        this.maxRetryAfter = maxRetryAfter;
     }
 
     /** text-embedding-3-large accepts 8192 tokens, roughly 4 chars per token. */
@@ -164,19 +186,47 @@ private <T> T attempt(LlmEmbeddingProvider provider, LlmCredentials credentials,
             } catch (RuntimeException e) {
                 LlmErrorCategory category = provider.classify(e);
                 if (retries >= MAX_RETRY_ATTEMPTS || !category.isRetryable()
-                        || !backoff(retries, category, credentials)) {
+                        || !backoff(retries, category, credentials, retryAfterHint(provider, e))) {
                     return handleFailure(category, credentials, e, failOpenValue, mayFailOpen);
                 }
             }
         }
     }
 
-    /** Sleeps before the next attempt. Returns false if interrupted, so the caller stops. */
-    private boolean backoff(int retries, LlmErrorCategory category, LlmCredentials credentials) {
-        long delayMs = retryBackoffMs * (retries + 1);
-        log.warn("Embedding attempt {}/{} failed — provider={} category={} model={}; retrying in {}ms",
+    /**
+     * The provider's stated retry delay, or zero when it has no opinion.
+     *
+     * <p>A provider that throws while reporting an error must not replace the error:
+     * the original failure is what the caller needs to see, so any secondary failure
+     * here degrades to "no hint" rather than propagating.
+     */
+    private Duration retryAfterHint(LlmEmbeddingProvider provider, RuntimeException failure) {
+        try {
+            return provider.retryAfter(failure).orElse(Duration.ZERO);
+        } catch (RuntimeException ignored) {
+            return Duration.ZERO;
+        }
+    }
+
+    /**
+     * Sleeps before the next attempt. Returns false if interrupted, so the caller stops.
+     *
+     * <p>Waits for whichever is longer: our own escalating schedule, or the delay the
+     * provider asked for. Retrying before a rate limiter's cooldown expires does not
+     * merely waste the attempt — the attempt itself is counted, so an impatient client
+     * extends the very window it is waiting on. The provider's number is remote input,
+     * so it is capped by {@link #MAX_RETRY_AFTER}; without that cap a single header
+     * could park a brain-init worker thread indefinitely.
+     */
+    private boolean backoff(int retries, LlmErrorCategory category, LlmCredentials credentials,
+                            Duration providerHint) {
+        long ownScheduleMs = retryBackoffMs * (retries + 1);
+        long hintMs = Math.min(Math.max(providerHint.toMillis(), 0L), maxRetryAfter.toMillis());
+        long delayMs = Math.max(ownScheduleMs, hintMs);
+        log.warn("Embedding attempt {}/{} failed — provider={} category={} model={}; retrying in {}ms{}",
                 retries + 1, MAX_RETRY_ATTEMPTS + 1, credentials.providerId(), category,
-                credentials.getOrDefault("model", "<unset>"), delayMs);
+                credentials.getOrDefault("model", "<unset>"), delayMs,
+                hintMs > ownScheduleMs ? " (honouring provider Retry-After)" : "");
         if (delayMs <= 0) {
             return true;
         }