约定与错误

分页

列表接口支持两个分页参数：

参数	默认值	说明
`page`	`1`	页码，小于 1 时按 1 处理。
`pageSize`	`50`	每页数量，当前最大值为 200。

列表接口通常支持一个轻量查询参数：

接口	查询参数	匹配字段
`/api/v1/items`	`q`	`id`、`name`、`type`
`/api/v1/craft/recipes`	`q`、`method`、`input`、`output`、`machine`	`recipeId`、合成方式、配方组、来源物品、机器、输入/输出物品
`/api/v1/characters`	`q`	`id`、`name`、`engName`、`profession`
`/api/v1/weapons`	`q`	`id`、`name`、`weaponType`、`weaponTypeName`
`/api/v1/equips`	`q`	`id`、`itemId`、`name`、`suitName`、`partType`
`/api/v1/world-energy`	`region`	`id`、`name`、`groupName`、`gameCategory`
`/api/v1/uniconnect/blueprint/search`	`text`	蓝图搜索文本
`/api/v1/uniconnect/blueprint/get`	`code`	蓝图码
`/api/v1/uniconnect/friend/search`	`keyword` 或 `uid`	玩家昵称或 UID
`/api/v1/uniconnect/friend/detail`	`role_id`	角色 ID
`/api/v1/uniconnect/friend/char`	`role_id`、`template_id`	角色 ID 与可选角色模板 ID

合成配方的 method 支持 MANUAL、MACHINE、FLUID_PUMP、MINING，大小写不敏感。 Perlica 统一链接技术™ 好友搜索中 keyword 和 uid 至少填写一个；同时填写时优先使用 keyword。

错误响应统一使用 error 包裹：

{
  "error": {
    "code": "NOT_FOUND",
    "message": "资源不存在"
  }
}

常见状态码：

状态码	code	触发场景
`401`	`Unauthorized`	请求缺少有效 Bearer token。
`404`	`NOT_FOUND`	路径不存在、详情资源不存在，或请求了不支持的语言。
`413`	`TOO_LARGE`	`/api/v1/i18n/{locale}` 请求的 `ids` 为空或超过最大单次查询量。
`503`	`UNICONNECT_UNAVAILABLE`	Perlica 统一链接技术™ runtime 不可用。
`500`	`INTERNAL_ERROR`	服务端未处理异常。

/api/v1/i18n/{locale} 支持：

br, cn, zh, zh-cn, de, en, fr, id, it, jp, ja, kr, ko,
mx, ru, tc, zh-tw, th, vn, vi