Proxy Errors

Kylon proxy endpoints return provider-compatible errors where practical. Shared proxy errors use a small JSON shape.

Missing or invalid API key

{
  "error": "unauthorized",
  "message": "Missing API key"
}

or:

{
  "error": "unauthorized",
  "message": "Invalid API key"
}

Fix: pass a valid Kylon key using x-api-key or Authorization: Bearer.

Workspace and connection access

A suspended or deleting workspace returns 403 with workspace_suspended or workspace_deleting. Connected tools also enforce the agent’s linked-connection access. App connection calls require explicit per-App grants and current App viewer access; see App Connection API. Enabling a skill is not required to reach a provider proxy route.

Missing request fields

Some endpoints validate required fields directly:

{
  "error": "Missing required fields: toolkit, method, url"
}

Fix: check the endpoint documentation and include the required fields.

Payment required

{
  "error": "payment_required",
  "code": 4002,
  "message": "Workspace credits are unavailable or exhausted",
  "details": {}
}

Fix: check the returned error, message, and details. Add eligible credits for payment_required or credit_capability_required. For script limits, follow the guidance in the 429 script_credit_rate_limited response and its reset time.

Provider errors

Buffered provider proxy routes generally return:

{
  "error": "proxy_error",
  "message": "Provider error message"
}

Model-compatible routes may return provider-shaped errors instead, such as OpenAI-style or Anthropic-style error objects.

Retry guidance

Status	Recommended action
`400`	Fix the request shape or missing fields
`401`	Check the API key and whether the endpoint requires an agent identity
`403`	Check workspace state, connection access, or current App access and grants
`402`	Check credit balance and eligible credit capabilities
`429`	Follow returned `guidance`, `Retry-After`, and quota headers; script-policy refusals may require user approval before resuming
`499`	Client disconnected; retry if still needed
`5xx`	Retry with exponential backoff if the operation is idempotent

Full error-code reference

Main Kylon API errors use the numeric code manifest listed in API error codes. Proxy endpoints also have route-specific string errors and provider-compatible envelopes; do not assume every proxy error contains a numeric code. For tool execution, inspect successful, error, statusCode, and any hint; a provider 429 is a retryable failure, not an empty successful result.

Getting Started

Concepts

Agents

Tutorials

CLI

Connections

Proxy

Proxy Errors

Missing or invalid API key

Workspace and connection access

Missing request fields

Payment required

Provider errors

Retry guidance

Full error-code reference

​Missing or invalid API key

​Workspace and connection access

​Missing request fields

​Payment required

​Provider errors

​Retry guidance

​Full error-code reference

Missing or invalid API key

Workspace and connection access

Missing request fields

Payment required

Provider errors

Retry guidance

Full error-code reference