Tencent/APIJSON · error · UnsupportedOperationException

找不到 version: ${version}, method: ${method.name()}, tag: ${ta

Error message

找不到 version: ${version}, method: ${method.name()}, tag: ${tag} 对应的 structure ！非开放请求必须是后端 Request 表中校验规则允许的操作！
 ${error}
如果需要则在 Request 表中新增配置！

What it means

For non-open requests (anything requiring structure validation), the parser looks up the JSON structure for the given version/method/tag in the backend 'Request' table via getStructure(...). If nothing is found, an UnsupportedOperationException is thrown: the operation is not permitted unless a matching Request-table entry whitelists it.

Source

Thrown at APIJSONORM/src/main/java/apijson/orm/AbstractParser.java:2288

		String _method = key == null ? null : getString(request, KEY_METHOD);
		if (_method != null) {
			RequestMethod method = RequestMethod.valueOf(_method); // 必须精准匹配，避免缓存命中率低
			this.setMethod(method);
			op.setMethod(method);
		}
	}

	protected M getRequestStructure(RequestMethod method, String tag, int version) throws Exception {
		// 获取指定的JSON结构 <<<<<<<<<<<<
		M object = null;
		String error = "";
		try {
			object = getStructure("Request", method.name(), tag, version);
		} catch (Exception e) {
			error = e.getMessage();
		}
		if (object == null) { // empty表示随意操作 || object.isEmpty()) {
			throw new UnsupportedOperationException("找不到 version: " + version + ", method: " + method.name() + ", tag: " + tag + " 对应的 structure ！" + "非开放请求必须是后端 Request 表中校验规则允许的操作！\n " + error + "\n如果需要则在 Request 表中新增配置！");
		}

		return object;
	}

	public static final Map<String, RequestMethod> KEY_METHOD_ENUM_MAP;
	static {
		KEY_METHOD_ENUM_MAP = new LinkedHashMap<>();
		KEY_METHOD_ENUM_MAP.put(KEY_GET, RequestMethod.GET);
		KEY_METHOD_ENUM_MAP.put(KEY_GETS, RequestMethod.GETS);
		KEY_METHOD_ENUM_MAP.put(KEY_HEAD, RequestMethod.HEAD);
		KEY_METHOD_ENUM_MAP.put(KEY_HEADS, RequestMethod.HEADS);
		KEY_METHOD_ENUM_MAP.put(KEY_POST, RequestMethod.POST);
		KEY_METHOD_ENUM_MAP.put(KEY_PUT, RequestMethod.PUT);
		KEY_METHOD_ENUM_MAP.put(KEY_DELETE, RequestMethod.DELETE);
	}

	private void parseMethodDirective(String key, RequestMethod keyMethod, @NotNull M request) throws Exception {

View on GitHub (pinned to 5284052872)

Solutions

Add a Request-table row matching method + tag + version that prescribes the allowed structure
Verify tag spelling/case and the method actually mapped (e.g. POST with 'INSERT': 'User' maps to method POST, tag User)
Align request 'version' with the max version present in the Request table (or add config for the new version)
If the operation should be open, use the open endpoints/keys instead of the non-open method

Example fix

-- before: no row
-- after: INSERT INTO Request (version, method, tag, structure, detail) VALUES (1, 'POST', 'User', '{ "INSERT": { "User": { "INSERT": ... } } }', 'allow add user');

Defensive patterns

Strategy: try-catch

Validate before calling

// Before allowing a tag through, check it is registered (requires access to the Request table, e.g. via a HEADS/GUESTS probe or cached config)
async function assertTagRegistered(api, method, tag, version) {
  const cfg = await api.queryRequestTable(method, tag, version); // your admin endpoint or cached copy
  if (cfg == null) throw new Error(`tag '${tag}' for ${method} v${version} is not registered in Request table`);
}

Try / catch

try { client.post(path, request); } catch (UnsupportedOperationException e) { if (e.getMessage().contains('对应的 structure')) { /* surface 'operation not permitted, contact admin' instead of a stack trace */ } else throw e; }

Prevention

Add the Request-table (method, tag, version) row in the same migration/PR that introduces a new table or operation
Automate a startup check that every tag your client can send exists in Request for the shipped version
Keep client version and Request-table max version in lockstep during releases

When it happens

Trigger: A POST/PUT request with tag 'User' when the Request table has no row for method POST + tag User + current version; using GETS/HEADS (non-open variants) with an unregistered tag; version mismatch (client sends version 3, table only has version <= 2 config).

Common situations: New table/operation added without inserting the Request-table permission config; tag typo or wrong case; METHOD directive key ('INSERT', 'UPDATE'...) differing from the tag registered; version bump on client before backend config updated; demo/backend init script not run so the Request table is empty.

Related errors

AI-assisted analysis of Tencent/APIJSON@5284052872 (2026-08-14). Data as JSON: /api/errors/dd8f4f2f0f3a6230. Report an issue: GitHub.