API 参考

错误码

Pikeway 网关返回的状态码和错误响应体。被网关拒绝的请求不会被转发,也不会扣费。

错误格式

根据路由分组不同,有两种 JSON 格式;部分错误会带额外字段。

网关:/gw、/cap、/ai/v1、/mock、/ws

json

{
  "error": "insufficient balance",
  "statusCode": 402
}

Agent API:/v1/*

json

{
  "code": 400,
  "message": "query is required (1-1000 characters)"
}

POST /v1/run 内部的网关调用在到达上游前被拒绝时(例如缺 key、余额不足、限流),会原样返回网关格式(error + statusCode)。处理错误时请同时检查 message 和 error。

额外字段

missing: 缺失的参数名数组(/gw、/cap 和 /v1/run 的 400)。/v1/run 还会在 input 里返回完整的输入 schema。
available: 找不到端点时,列出该提供方最多 30 个 METHOD /path(/v1/inspect 和 /v1/run 的 404)。
plan, included: 出现在 429 套餐额度用完时。
byok, provider, signupUrl, keyHint: 自带 key 的 API 缺少你自己的上游 key 时,出现在 403 中。
errors[]: 被网关拒绝的 GraphQL 端点请求还会返回 GraphQL 风格的 errors 数组,extensions.code = "PIKEWAY_REJECTED"。

400 · /gw

{
  "error": "missing required query parameters",
  "missing": ["address"],
  "statusCode": 400
}

上游错误

请求到达提供方后,/gw 原样返回提供方的状态码和 body。只有 2xx 响应计费,否则 X-Pikeway-Cost 为 0。如果提供方返回 2xx 但业务码表示失败,则不计费并设置 X-Pikeway-Upstream-Error: business-code(提供方的限流业务码会被改成 429 并带 Retry-After: 1)。如果完全没有拿到响应,网关返回 502。

状态码

400 Bad Request

消息	出现位置	含义 / 处理方式
missing required query parameters	/gw	匹配到的端点有必填查询参数为空,见 missing。
request does not match the API's schema: …	/gw	提供方开启了请求校验,请求未通过。
request body must be a JSON object	/gw	该端点会合并固定 JSON body,而你的 body 不是 JSON 对象。
missing service slug	/gw, /mock	路径里没有 API slug。
missing required parameters	/cap	缺少能力的必填参数,见 missing。
no provider could be called with these parameters	/cap	你的参数无法填满任何提供方的路径模板。
invalid JSON body · missing 'model' · read body failed	/ai/v1	请求 body 不是合法 JSON,或缺少 model。
query is required (1-1000 characters)	/v1/discover	query 为空或过长。
provider and endpoint are required (see POST /v1/discover)	/v1/inspect, /v1/run	需要同时提供这两个字段才能定位端点。
missing required input	/v1/run	缺少必填的路径或查询参数,如 pathParams.id,见 missing 和 input。
async runs need an API key (x402 pays per synchronous run)	/v1/run	未带 key 却传了 async: true。
body must be JSON …	/v1/*	请求 body 无法解析。

401 Unauthorized

消息	出现位置	含义 / 处理方式
missing API key (Authorization: Bearer pk-...)	/gw, /ai/v1, /v1/*	没有发送 key。
invalid or revoked API key	all	key 不存在、已吊销或已过期。请在控制台 → Keys 新建。
WebSocket requires a Pikeway key (Authorization header or ?key=)	/ws	WebSocket 连接必须带 key。

402 Payment Required

消息	出现位置	含义 / 处理方式
insufficient balance	/gw, /ai/v1, /ws	余额低于本次调用价格(/ai/v1 为余额小于等于 0)。请在控制台充值。
api key spend limit reached	/gw	本次调用会超出该 key 的消费上限。请调高上限或换一把 key。

403 Forbidden

消息	出现位置	含义 / 处理方式
client IP not allowed for this API key	all	调用方 IP 不在该 key 的 CIDR 白名单内。
request origin not allowed for this API key	all	浏览器 key:缺少 Origin/Referer,或不在该 key 的白名单内。
this API requires a subscription …	/gw, /ws	只卖套餐的 API。请在它的市场页面选择套餐。
this API key is paused: … · this account is paused: …	/gw	Pikeway 暂停了该 key 或账户,请联系支持。
… runs on your own … account …	/gw, /v1/run	自带 key 的 API:请在控制台 → Connections 添加你的上游 key。包含 byok、provider、signupUrl。

404 Not Found

消息	出现位置	含义 / 处理方式
no such API service: {slug}	/gw, /mock, /ws	slug 不存在。无权调用的私有 API 也返回同样的错误。
unknown capability: {slug} · no live provider for capability {slug}	/cap	能力不存在或已停用,或没有在线的提供方(或没有匹配 ?provider= 的)。
unknown model: {model}	/ai/v1	有效的模型 id 见 GET /ai/v1/models。
no endpoint matches {METHOD} /{path} · no example response yet …	/mock	没有这个端点,或该端点还没有可供模拟的示例响应。
unknown provider · unknown endpoint … on …	/v1/inspect, /v1/run	用 /v1/discover 查找有效的 provider + endpoint,见 available。
run not found	/v1/runs	你的账户下没有该 id 的运行。

405 Method Not Allowed

消息	出现位置	含义 / 处理方式
GET only · POST only · use POST · use GET	/cap, /ai/v1, /v1/*	该接口不支持此 HTTP 方法。

409 Conflict

消息	出现位置	含义 / 处理方式
duplicate request: this Idempotency-Key was already used (call …)	/gw	这把 key 已用过同一个 Idempotency-Key;消息里带原调用 id。
Idempotency-Key was already used for a different request	/gw	新请求请使用新的 Idempotency-Key。
run already finished	/v1/runs/{id}/stop	异步运行已不在 QUEUED 或 RUNNING 状态;响应里带 status。

429 Too Many Requests

消息	出现位置	含义 / 处理方式
rate limit exceeded	/gw, /ws	超过了该 API 的单 key 限流(或套餐的每分钟限制)。
spike arrest: too many requests per second	/gw	每秒突发限制。Retry-After: 1。
plan quota exhausted for this period	/gw	套餐为硬性额度且已用完。包含 plan 和 included。
upstream is at capacity for this endpoint, retry in a second (not charged)	/gw	共享的上游额度繁忙。Retry-After: 1。
upstream's shared per-minute quota is used up, retry shortly (not charged)	/gw	上游每分钟共享额度用完。Retry-After: 20。
mock rate limit exceeded (30/min)	/mock	Mock 响应每个 IP 每分钟最多 30 次。
too many concurrent WebSocket connections for this key (max 10)	/ws	请先关闭已有连接。

有 Retry-After(秒)时请按其等待。被限流的请求从不扣费。

5xx

消息	出现位置	含义 / 处理方式
route lookup failed · auth lookup failed · balance check failed · …	all	网关内部错误(500),可以重试。
upstream request failed (timeout \| network \| canceled \| blocked \| status)	/gw	没有拿到提供方的可用响应(502)。不扣费;会返回 X-Pikeway-Call-Id。
upstream LLM request failed: …	/ai/v1	无法连接模型提供方(502),不扣费。
billing is temporarily unavailable; the request was not forwarded and you were not charged	/gw	503。账本暂不可用,网关拒绝转发。
could not record the charge, so the response was not delivered; you will not be charged (call …)	/gw	503。上游已响应但扣费无法记录;请重试。
this API is paused by Pikeway: … · paid calls are temporarily paused: …	/gw	503。该 API、其提供方或全部付费调用被暂停。