Retrofit携带API Key发起GET请求返回401错误问题排查

开发者阿泽

2026-8-26

问题根因

两个报错分别对应不同的配置错误：

HTTP 401的核心原因是请求头的认证字段名称、格式写错：你当前配置的请求头键为api-key，但该国家数据接口要求认证信息放在Authorization请求头中，且值必须以Bearer 作为前缀拼接真实API Key，服务端读取不到合法的认证字段，就会返回「未检测到有效API Key」的401错误。
给@GET路径前加"/"触发404是Retrofit路径拼接规则导致的：当@GET注解里的路径以/开头时，Retrofit会忽略baseUrl中的路径段，直接把域名和该路径拼接，你当前baseUrl是https://countryapi.io/api/，加/后最终请求地址会变成https://countryapi.io/all，丢失了/api路径段，自然返回404。

修复方案

修正认证请求头配置
不推荐把密钥硬编码在@Headers注解中（后续换密钥、多接口复用都不方便），更合理的方式是通过OkHttp拦截器统一注入认证头，修改Hilt模块中Retrofit的提供逻辑：

@Module
@InstallIn(SingletonComponent::class)
object AppModule {

    @Provides
    @Singleton
    fun provideApi(): CountryApi {
        // 配置OkHttp客户端，统一添加认证头
        val okHttpClient = OkHttpClient.Builder()
            .addInterceptor { chain ->
                val request = chain.request().newBuilder()
                    // 注意这里的键名和Bearer前缀，替换成你自己的真实API Key
                    .addHeader("Authorization", "Bearer 替换为你的真实API Key")
                    .build()
                chain.proceed(request)
            }
            .build()

        return Retrofit.Builder()
            .baseUrl("https://countryapi.io/api/")
            .client(okHttpClient) // 传入配置好的OkHttp实例
            .addConverterFactory(GsonConverterFactory.create())
            .build()
            .create(CountryApi::class.java)
    }
}

如果暂时不想改拦截器逻辑，也可以直接修改接口上的@Headers注解，同样要注意键名和前缀：

interface CountryApi {
    @Headers("Authorization: Bearer 替换为你的真实API Key")
    @GET("all")
    suspend fun getCountryData(): List<CountryDto>
}

额外提示：不要把API Key硬编码在代码里，建议放到local.properties或者通过BuildConfig注入，避免密钥泄露。

修正请求路径
保持@GET注解中的路径为"all"即可，不要加开头的/，和当前baseUrl拼接后最终请求地址为https://countryapi.io/api/all，和接口要求的地址完全一致，不会触发404。

改完之后重新运行项目即可正常获取数据，如果还是报错，可以添加OkHttp日志拦截器打印完整请求日志，确认请求头、请求地址是否符合要求。

内容的提问来源于stack exchange，提问作者SethC601