Errors

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

REST / MCP Shared HTTP 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
504	`GATEWAY_TIMEOUT`	Agent response timed out
502	`AGENT_VALIDATION_FAILED`	Agent rejected params
502	`AGENT_QUERY_FAILED`	SQL execution failed
502	`AGENT_QUERY_TIMEOUT`	Query exceeded timeout
502	`AGENT_DB_UNREACHABLE`	Agent cannot reach the DB
502	`AGENT_INTERNAL_ERROR`	Unexpected agent error

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

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`

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`