dromara/Sa-Token · error · ApiKeyException

12303

12303

Error message

API Key 已被禁用:

What it means

Thrown by SaApiKeyTemplate.checkApiKey(String) when the key record exists and is not expired but ak.getIsValid() is false — the key was administratively disabled. Code 12303 marks a disabled key, distinct from unknown (12301) and expired (12302).

Source

Thrown at sa-token-plugin/sa-token-apikey/src/main/java/cn/dev33/satoken/apikey/template/SaApiKeyTemplate.java:133

		}
		return apiKeyModel;
	}

	/**
	 * 校验 ApiKey，成功返回 ApiKeyModel，失败则抛出异常
	 * @param apiKey /
	 * @return /
	 */
	public ApiKeyModel checkApiKey(String apiKey) {
		ApiKeyModel ak = getApiKey(apiKey);
		if(ak == null) {
			throw new ApiKeyException("无效 API Key: " + apiKey).setApiKey(apiKey).setCode(SaApiKeyErrorCode.CODE_12301);
		}
		if(ak.timeExpired()) {
			throw new ApiKeyException("API Key 已过期: " + apiKey).setApiKey(apiKey).setCode(SaApiKeyErrorCode.CODE_12302);
		}
		if(! ak.getIsValid()) {
			throw new ApiKeyException("API Key 已被禁用: " + apiKey).setApiKey(apiKey).setCode(SaApiKeyErrorCode.CODE_12303);
		}
		return ak;
	}

	/**
	 * 持久化：ApiKeyModel
	 * @param ak /
	 */
	public void saveApiKey(ApiKeyModel ak) {
		if(ak == null) {
			return;
		}
		// 数据自检
		ak.checkByCanSaved();

		// 保存 ApiKeyModel
		String saveKey = splicingApiKeySaveKey(ak.getApiKey());
		if(ak.timeExpired()) {

View on GitHub (pinned to ac2c7f6e94)

Solutions

  1. Re-enable the key: load the model, setIsValid(true), and save it back (or use the template's update API)
  2. If the disable was intentional, remove the key from the client's configuration and issue a replacement
  3. Audit who/what disabled the key before re-enabling it

Example fix

// before
saApiKeyTemplate.checkApiKey(disabledKey); // isValid=false -> throws 12303

// after
ApiKeyModel ak = saApiKeyTemplate.getApiKey(disabledKey);
ak.setIsValid(true);
saApiKeyTemplate.updateApiKey(ak);
saApiKeyTemplate.checkApiKey(disabledKey);
Defensive patterns

Strategy: try-catch

Validate before calling

ApiKeyModel ak = saApiKeyTemplate.getApiKey(apiKey);
if (ak != null && !Boolean.TRUE.equals(ak.getIsValid())) {
    return unavailable("api key disabled");
}

Try / catch

catch (ApiKeyException e) { if (e.getCode() == SaApiKeyErrorCode.CODE_12303) { /* 403: key disabled, alert ops */ } else throw e; }

Prevention

When it happens

Trigger: Calling checkApiKey (directly or through checkApiKeyScope / checkApiKeyScopeOr) on a key whose isValid flag was set to false, e.g. after updateApiKey or a disable operation.

Common situations: Security incident response disabling a leaked key; toggling isValid=false during testing and forgetting to re-enable; a disabled key still configured in a downstream client.

Related errors

AI-assisted analysis of dromara/Sa-Token@ac2c7f6e94 (2026-08-14). Data as JSON: /api/errors/6e4ebe671cb1d216. Report an issue: GitHub.