Errors

Failed calls return an error envelope instead of result:


{
  "request_id": "01J5ABCDEF1234567890ABCDEF01",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "input validation failed",
    "outcome": "not_started"
  }
}

Branch on code and outcome. message is a fixed, safe text for people; it never contains SQL, driver errors, paths, credentials, or the values you sent. Some errors add a fixed reason, such as UPSTREAM_HTTP_STATUS. The detail behind an error is in the agent’s local log.

Codes

HTTP	Code	Meaning
400	`INVALID_REQUEST`	The request is malformed: bad JSON, bad Base64, broken multipart
400	`VALIDATION_FAILED`	The input does not match the capability’s schema
401	`AUTH_FAILED`	Missing or invalid API key
403	`CAPABILITY_DENIED`	The API key may not call this capability
403	`PERMISSION_DENIED`	The source IP or browser origin is not allowed, or the agent may not access a file it needs
404	`NOT_FOUND`	Unknown capability, no matching file, or an expired download link
409	`CONFLICT`	A database constraint was violated, a file to save already exists, or the agent was restarted with a different configuration while the call was in flight
409	`SOURCE_CHANGED`	A file or folder changed while it was being read
413	`LIMIT_EXCEEDED`	The request body is larger than the gateway allows
415	`INVALID_REQUEST`	Unsupported `Content-Type`
422	`LIMIT_EXCEEDED`	A capability limit was exceeded: input size, rows, output size, files
422	`APP_*`	A business error returned by a code capability
429	`RATE_LIMITED`	A gateway, authentication, or capability rate limit was reached
500	`INTERNAL_ERROR`	An unexpected failure
502	`EXECUTION_FAILED`	The database, upstream API, file operation, or code failed
502	`OUTPUT_INVALID`	The result did not match the declared output
502	`OUTCOME_UNKNOWN`	The agent could not confirm whether a commit or rollback happened
503	`BUSY`	The gateway or agent is at capacity; nothing was run
503	`AGENT_OFFLINE`	No agent is connected
503	`DEPENDENCY_UNAVAILABLE`	A database, upstream API, or required gateway setting is unavailable
504	`EXECUTION_TIMEOUT`	The capability’s timeout or the caller’s deadline was reached

Download failures follow the same table, except that a range request gets HTTP 416. MCP tool errors carry the same codes inside a successful HTTP response; see MCP.

For RATE_LIMITED, the message tells you which limit was hit; see Troubleshooting.

Outcome

outcome says what happened on the on-prem side, independent of the code:

Outcome	Meaning	What to do
`not_started`	Nothing ran	Safe to try again
`no_change`	It ran and changed nothing, for example a failed read	Safe to try again
`rolled_back`	It made changes, and they were all rolled back	Fix the cause, then try again
`committed`	All changes were completed	Do not repeat it; the change is done
`unknown`	Changes may or may not have happened	Check the real state first

Trust outcome, not the code or the capability’s annotations. EXECUTION_TIMEOUT, for example, can come with not_started or unknown. Treat a call whose response you never received as unknown. Never retry an operation with unknown automatically: check the real state first, as described in Uncertain outcomes.

Application errors

A code capability can return its own business error with onprest.PublicError(code, message) in the Go SDK. The code must look like APP_CUSTOMER_NOT_FOUND: APP_, an uppercase letter, then up to 59 uppercase letters, digits, or underscores. The message is 1 to 1024 bytes of UTF-8 without control characters and is returned exactly as written, so write it for the caller. Anything else, including an invalid code, becomes EXECUTION_FAILED with a generic message.