Errors

Onprest returns stable error codes with public client-facing messages, and keeps sensitive detail out of external responses.

HTTP Boundary Errors

HTTP	Code	Meaning
401	`GATEWAY_AUTH_FAILED`	API key is missing or invalid
403	`GATEWAY_CAPABILITY_DENIED`	API key cannot call the capability
403	`GATEWAY_IP_DENIED`	Source IP is not allowed
429	`GATEWAY_RATE_LIMITED`	Rate limit exceeded
500	`GATEWAY_INTERNAL_ERROR`	Unexpected gateway error
503	`GATEWAY_AGENT_OFFLINE`	Agent is not connected
503	`AGENT_BUSY`	Agent execution slots and bounded waiting queue are full
504	`GATEWAY_TIMEOUT`	Agent response timed out
400	`AGENT_VALIDATION_FAILED`	Agent rejected params (REST)
502	`AGENT_QUERY_FAILED`	SQL execution failed
504	`AGENT_QUERY_TIMEOUT`	Query exceeded timeout (REST)
502	`AGENT_DB_UNREACHABLE`	Agent cannot reach the DB
502	`AGENT_INTERNAL_ERROR`	Unexpected agent error

The agent-originated rows above are REST mappings. MCP tools/call returns those runtime failures as HTTP 200 tool results with isError: true. Gateway boundary errors use the HTTP status shown above.

Endpoint HTTP Errors

HTTP	Code	Applies to	Meaning
400	`GATEWAY_INVALID_REQUEST`	REST	JSON parse failure or invalid content type
404	`GATEWAY_CAPABILITY_NOT_FOUND`	REST	capability path does not exist
405	`GATEWAY_METHOD_NOT_ALLOWED`	REST / MCP	HTTP method is not allowed
409	`GATEWAY_AGENT_ALREADY_CONNECTED`	WebSocket	another agent is already connected

MCP JSON-RPC Errors

These are returned as JSON-RPC errors with HTTP 200.

JSON-RPC code	Code	Meaning
-32700	`PARSE_ERROR`	JSON cannot be parsed
-32600	`INVALID_REQUEST`	Invalid JSON-RPC shape
-32601	`METHOD_NOT_FOUND`	Unsupported method
-32602	`INVALID_PARAMS`	Invalid `tools/call` name or arguments
-32000	`GATEWAY_AGENT_OFFLINE`	`tools/list` metadata is unavailable

Known-tool execution failures are not JSON-RPC errors. They are MCP results whose isError is true, with the stable agent code/message under structuredContent.error and one text content item. A valid notification has no id and returns HTTP 202 with an empty body.

Public Error Body

REST and HTTP-level MCP errors include error.code and public error.message.


{
  "error": {
    "code": "AGENT_QUERY_FAILED",
    "message": "database query failed"
  }
}

message is part of the public API contract. Agent validation messages may identify the invalid field and reason so callers can fix their request. Clients should still branch on code.

Agent-originated raw detail such as stack traces, SQL text, DB-specific error text, DB credentials, and submitted param values is written only to onprest-agent.log when needed. It is not sent to gateway and is not included in gateway stdout or HTTP responses.

Agent-Originated Messages

For agent errors, gateway returns the agent’s public code and message unchanged. Secret detail stays in the agent local log.

Code	Public message
`GATEWAY_CAPABILITY_NOT_FOUND`	`capability is not defined`
`AGENT_VALIDATION_FAILED`	one of the validation messages below
`AGENT_QUERY_FAILED`	`database query failed` or `response exceeds policy.max_bytes`
`AGENT_QUERY_TIMEOUT`	`query exceeded policy.timeout`
`AGENT_DB_UNREACHABLE`	`database is unreachable`
`AGENT_INTERNAL_ERROR`	`agent internal error`
`AGENT_BUSY`	`agent request queue is full`

Validation messages use the parameter name but never the submitted value.

Condition	Public message
unknown parameter	`unknown param: {name}`
missing required parameter	`required param missing: {name}`
string type mismatch	`{name}: must be string`
string pattern mismatch	`{name}: does not match pattern`
string too short	`{name}: below minLength`
string too long	`{name}: above maxLength`
invalid email	`{name}: must be email`
invalid UUID	`{name}: must be uuid`
invalid date	`{name}: must be date`
invalid date-time	`{name}: must be date-time`
invalid URI	`{name}: must be uri`
URI without scheme	`{name}: must include URI scheme`
integer type mismatch	`{name}: must be integer`
integer below minimum	`{name}: below minimum`
integer above maximum	`{name}: above maximum`
number type mismatch	`{name}: must be number`
number below minimum	`{name}: below minimum`
number above maximum	`{name}: above maximum`
boolean type mismatch	`{name}: must be boolean`
enum mismatch	`{name}: not in enum`