{
"code": 400,
"message": "query is required (1-1000 characters)"
}
POST /v1/run returns the gateway shape (error + statusCode) unchanged when the inner gateway call is rejected before reaching the upstream, e.g. missing key, insufficient balance or rate limit. Check both message and error when handling errors.
Extra fields
missing: array of missing parameter names (400 on /gw, /cap and /v1/run). /v1/run also returns the full input schema in input.
available: up to 30 METHOD /path strings for the provider when an endpoint isn't found (404 on /v1/inspect and /v1/run).
plan, included: on 429 plan quota exhausted.
byok, provider, signupUrl, keyHint: on 403 for bring-your-own-key APIs when your own provider key is missing.
errors[]: GraphQL endpoints rejected by the gateway also return a GraphQL-style errors array with extensions.code = "PIKEWAY_REJECTED".
When the call reaches the provider, /gw returns the provider's own status and body unchanged. Only 2xx responses are billed; X-Pikeway-Cost is 0 otherwise. If the provider returned 2xx but its business code signals failure, the call is not billed and X-Pikeway-Upstream-Error: business-code is set (a provider-side throttle code is turned into 429 with Retry-After: 1). If no response came back at all, you get 502 from the gateway.
Status codes
400 Bad Request
Message
Where
Meaning / what to do
missing required query parameters
/gw
A required query parameter of the matched endpoint is empty. See missing.
request does not match the API's schema: …
/gw
The provider enabled request validation and the request failed it.
request body must be a JSON object
/gw
The endpoint merges a fixed JSON body and yours is not a JSON object.
missing service slug
/gw, /mock
The path has no API slug.
missing required parameters
/cap
A required capability parameter is missing. See missing.
no provider could be called with these parameters
/cap
No provider's path template could be filled from your parameters.
invalid JSON body · missing 'model' · read body failed
/ai/v1
The request body is not valid JSON or has no model.
query is required (1-1000 characters)
/v1/discover
Empty or too long query.
provider and endpoint are required (see POST /v1/discover)
/v1/inspect, /v1/run
Both fields are needed to pick an endpoint.
missing required input
/v1/run
A required path or query parameter is missing, e.g. pathParams.id. See missing and input.
async runs need an API key (x402 pays per synchronous run)
/v1/run
async: true was sent without a key.
body must be JSON …
/v1/*
The request body could not be parsed.
401 Unauthorized
Message
Where
Meaning / what to do
missing API key (Authorization: Bearer pk-...)
/gw, /ai/v1, /v1/*
No key was sent.
invalid or revoked API key
all
Unknown, revoked or expired key. Create a new one in Console → Keys.
WebSocket requires a Pikeway key (Authorization header or ?key=)
/ws
WebSocket connections always need a key.
402 Payment Required
Message
Where
Meaning / what to do
insufficient balance
/gw, /ai/v1, /ws
Your balance is below the price of this call (on /ai/v1: your balance is 0 or less). Top up in the console.
api key spend limit reached
/gw
This call would exceed the key's spend limit. Raise the limit or use another key.
403 Forbidden
Message
Where
Meaning / what to do
client IP not allowed for this API key
all
The caller's IP is outside the key's CIDR allowlist.
request origin not allowed for this API key
all
Browser key: Origin/Referer missing or not on the key's allowlist.
this API requires a subscription …
/gw, /ws
Subscription-only API. Pick a plan on its marketplace page.
this API key is paused: … · this account is paused: …
/gw
Pikeway paused the key or account. Contact support.
… runs on your own … account …
/gw, /v1/run
Bring-your-own-key API: add your provider key in Console → Connections. Includes byok, provider, signupUrl.
404 Not Found
Message
Where
Meaning / what to do
no such API service: {slug}
/gw, /mock, /ws
Unknown slug. Private APIs you are not allowed to call return the same error.
unknown capability: {slug} · no live provider for capability {slug}
/cap
Unknown or disabled capability, or none of its providers is live (or matches ?provider=).
unknown model: {model}
/ai/v1
See GET /ai/v1/models for valid ids.
no endpoint matches {METHOD} /{path} · no example response yet …
/mock
No such endpoint, or the endpoint has no example response to mock yet.
unknown provider · unknown endpoint … on …
/v1/inspect, /v1/run
Use /v1/discover to find valid provider + endpoint pairs. See available.
run not found
/v1/runs
No run with that id for your account.
405 Method Not Allowed
Message
Where
Meaning / what to do
GET only · POST only · use POST · use GET
/cap, /ai/v1, /v1/*
Wrong HTTP method for this route.
409 Conflict
Message
Where
Meaning / what to do
duplicate request: this Idempotency-Key was already used (call …)
/gw
The same Idempotency-Key was already used with this key; the original call id is included.
Idempotency-Key was already used for a different request
/gw
Pick a new Idempotency-Key for a new request.
run already finished
/v1/runs/{id}/stop
The async run is no longer QUEUED or RUNNING; status is included.
429 Too Many Requests
Message
Where
Meaning / what to do
rate limit exceeded
/gw, /ws
You exceeded the API's per-key rate limit (or your plan's per-minute limit).
spike arrest: too many requests per second
/gw
Per-second burst limit. Retry-After: 1.
plan quota exhausted for this period
/gw
Your plan has a hard quota and it is used up. Includes plan and included.
upstream is at capacity for this endpoint, retry in a second (not charged)
/gw
Shared upstream capacity is busy. Retry-After: 1.
upstream's shared per-minute quota is used up, retry shortly (not charged)