一句话总结：本文整理了Spring AI接入OpenAI时最常见的401/429/超时报错，提供排查清单+完整解决代码，5分钟定位问题。

---

一、报错现象

刚用Spring AI接入OpenAI，一运行就报错？别慌，90%的问题都集中在以下3种：

1.1 401 Unauthorized

org.springframework.web.client.HttpClientErrorException$Unauthorized: 
401 Unauthorized: "{
    "error": {
        "message": "Incorrect API key provided...",
        "type": "invalid_request_error"
    }
}"

1.2 429 Too Many Requests

org.springframework.web.client.HttpClientErrorException$TooManyRequests: 
429 Too Many Requests: "{
    "error": {
        "message": "Rate limit reached...",
        "type": "rate_limit_error"
    }
}"

1.3 Connection Timeout

org.springframework.web.ResourceAccessException: 
I/O error on POST request for "https://api.openai.com/v1/chat/completions": 
Connect timed out

---

二、原因排查清单（按优先级）

2.1 401排查（API Key问题）

排查项	检查方法	解决方式
Key是否正确	对比OpenAI后台的Key前10位	重新复制，注意无空格
Key是否过期	OpenAI后台查看额度	充值或换Key
环境变量未加载	System.getenv("OPENAI_API_KEY")打印	检查配置优先级
Key前多了Bearer	部分SDK自动加，手动配置时重复	只填Key值，不加Bearer

最常见错误：从OpenAI后台复制Key时，前面多了空格或换行符。

// 验证Key是否加载正确
@PostConstruct
public void checkApiKey() {
    String key = System.getenv("OPENAI_API_KEY");
    System.out.println("Key长度: " + (key != null ? key.length() : 0));
    System.out.println("Key前10位: " + (key != null ? key.substring(0, 10) : "null"));
}

2.2 429排查（速率限制）

排查项	检查方法	解决方式
请求频率	统计每分钟请求数	加限流或降频
并发数	查看线程池配置	控制并发数
账户等级	OpenAI后台查看Rate Limits	升级账户
是否共享Key	检查是否有其他服务在用	单独分配Key

OpenAI速率限制参考：

• GPT-3.5：3,500 RPM（每分钟请求数）
• GPT-4：200 RPM
• 新注册账户可能更低

2.3 超时排查（网络问题）

排查项	检查方法	解决方式
能否ping通	curl https://api.openai.com	使用代理或换网络
代理配置	检查系统代理/IDE代理	配置RestTemplate代理
超时时间	默认可能只有5秒	增加到30秒
DNS解析	nslookup api.openai.com	换DNS或hosts

---

三、完整解决代码

3.1 application.yml配置（推荐）

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}  # 从环境变量读取，不要硬编码
      base-url: https://api.openai.com  # 国内可换代理地址
      chat:
        options:
          model: gpt-3.5-turbo
          temperature: 0.7
          # 超时配置
      timeout:
        connect: 30000  # 连接超时30秒
        read: 60000     # 读取超时60秒

# 自定义RestTemplate配置（解决超时和重试）
openai:
  client:
    max-retries: 3           # 最大重试次数
    retry-delay: 1000        # 重试间隔1秒
    max-connections: 20      # 最大连接数
    max-connections-per-route: 10  # 单路由最大连接

3.2 RestTemplate配置类（带超时+重试+代理）

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.client.DefaultResponseErrorHandler;
import org.springframework.http.HttpStatus;
import org.springframework.http.client.ClientHttpResponse;
import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.Proxy;

@Configuration
public class OpenAIClientConfig {

    @Bean
    public RestTemplate openaiRestTemplate() {
        // 1. 配置超时
        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(30000);  // 30秒连接超时
        factory.setReadTimeout(60000);     // 60秒读取超时

        // 2. 配置代理（国内环境需要）
        // factory.setProxy(new Proxy(Proxy.Type.HTTP, 
        //     new InetSocketAddress("127.0.0.1", 7890)));

        RestTemplate restTemplate = new RestTemplate(factory);

        // 3. 自定义错误处理（区分401/429/其他）
        restTemplate.setErrorHandler(new DefaultResponseErrorHandler() {
            @Override
            public void handleError(ClientHttpResponse response) throws IOException {
                HttpStatus statusCode = (HttpStatus) response.getStatusCode();
                String body = new String(response.getBody().readAllBytes());

                switch (statusCode) {
                    case UNAUTHORIZED:
                        throw new RuntimeException("401: API Key无效或过期，请检查OPENAI_API_KEY。详情: " + body);
                    case TOO_MANY_REQUESTS:
                        throw new RuntimeException("429: 请求过于频繁，请降低调用频率或升级账户。详情: " + body);
                    case BAD_GATEWAY:
                    case SERVICE_UNAVAILABLE:
                        throw new RuntimeException("502/503: OpenAI服务暂不可用，请稍后重试。详情: " + body);
                    default:
                        super.handleError(response);
                }
            }
        });

        return restTemplate;
    }
}

3.3 带重试的ChatClient封装

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Service;

@Service
public class OpenAIChatService {

    private final ChatClient chatClient;

    public OpenAIChatService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @Retryable(
        retryFor = {RuntimeException.class},
        maxAttempts = 3,
        backoff = @Backoff(delay = 1000, multiplier = 2)  // 1秒、2秒、4秒退避
    )
    public String chat(String message) {
        return chatClient.prompt()
            .user(message)
            .call()
            .content();
    }
}

// 启用重试需要在启动类加@EnableRetry

3.4 限流器（防止429）

import com.google.common.util.concurrent.RateLimiter;
import org.springframework.stereotype.Component;
import java.util.concurrent.TimeUnit;

@Component
public class OpenAIRateLimiter {

    // GPT-3.5限制3500 RPM，这里保守设置为50/秒
    private final RateLimiter rateLimiter = RateLimiter.create(50.0);

    public void acquire() {
        rateLimiter.acquire();
    }

    public boolean tryAcquire(long timeout, TimeUnit unit) {
        return rateLimiter.tryAcquire(timeout, unit);
    }
}

// 使用
@Service
public class ChatService {
    @Autowired
    private OpenAIRateLimiter rateLimiter;

    public String safeChat(String message) {
        rateLimiter.acquire();  // 阻塞等待获取令牌
        return chatClient.prompt().user(message).call().content();
    }
}

---

四、验证方法

4.1 curl测试（不依赖Java代码）

# 测试Key是否有效
curl https://api.openai.com/v1/models   -H "Authorization: Bearer $OPENAI_API_KEY"   -H "Content-Type: application/json"

# 测试对话接口
curl https://api.openai.com/v1/chat/completions   -H "Authorization: Bearer $OPENAI_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

4.2 日志输出检查

// 开启HttpClient调试日志
logging.level.org.springframework.web.client.RestTemplate=DEBUG
logging.level.org.apache.http=DEBUG

4.3 健康检查端点

@RestController
public class HealthController {

    @Autowired
    private OpenAIChatService chatService;

    @GetMapping("/health/openai")
    public Map<String, Object> checkOpenAI() {
        try {
            String response = chatService.chat("Hi");
            return Map.of(
                "status", "UP",
                "response", response.substring(0, 20),
                "timestamp", System.currentTimeMillis()
            );
        } catch (Exception e) {
            return Map.of(
                "status", "DOWN",
                "error", e.getMessage(),
                "timestamp", System.currentTimeMillis()
            );
        }
    }
}

---

五、扩展：国内环境特殊处理

5.1 使用代理地址

spring:
  ai:
    openai:
      base-url: https://api.openai-proxy.com  # 第三方代理
      api-key: ${OPENAI_API_KEY}

5.2 使用国内模型（备选方案）

# 通义千问（阿里云）
spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}

# 文心一言（百度）
spring:
  ai:
    qianfan:
      api-key: ${QIANFAN_API_KEY}
      secret-key: ${QIANFAN_SECRET_KEY}

---

六、总结

报错码	根因	快速解决
401	API Key无效	检查Key格式、环境变量、是否过期
429	请求过快	加RateLimiter、降频、升级账户
Timeout	网络问题	增加超时时间、配置代理、检查DNS

核心原则：生产环境永远不要硬编码API Key，永远加限流和重试。

---

---

🏆 CSDN博客专家 ｜ JavaAgent架构师

十年Java分布式系统架构经验，专注AI Agent、LLM应用开发、企业级AI架构设计。

🔨 开源贡献：RPC框架、消息中间件、ORM框架作者
📖 专栏连载中：

• 《前端AI工程化》— SSE/流式渲染/Function Calling/企业级AI架构
• 《Java体系也能玩转AI》— Spring AI / Agent框架 / MCP / 工作流
• 《从0构建Agent系统》— 数字员工 / SOP模型库 / 企业级落地

💬 技术交流：前端AI工程化、Java AI化、Agent框架选型、企业级AI落地

觉得有用？点赞 + 收藏 + 关注，不错过每一期干货！

时代不会淘汰你，淘汰你的是自己，学起来骚年！