Version: v2.0

Error Reference

When running workflows (completions, chat, evaluators, or custom workflows), Agenta returns structured errors with a type URL, a code, and a human-readable message. This page documents all error types.

Error response format

Error responses include:

{
  "status": {
    "code": 400,
    "message": "Human-readable description of the error.",
    "type": "https://agenta.ai/docs/misc/errors#v0:schemas:invalid-secrets"
  }
}

Field	Description
`code`	HTTP status code (e.g., 400, 500)
`message`	A human-readable description of what went wrong
`type`	A URL pointing to the relevant section on this page

Schema errors

These errors occur when the request payload doesn't match expected schemas — wrong types, missing fields, or invalid values.

Invalid secrets {#v0:schemas:invalid-secrets}

Code: 400

The API key or provider credentials needed to call the LLM are missing or invalid.

Common causes:

No API key configured for the model you're trying to use.
The secrets/credentials provided are the wrong type.

How to fix:

Go to Settings > Providers & Models and add the API key for your provider (OpenAI, Anthropic, etc.).
If using the SDK programmatically, ensure secrets are correctly passed via the vault or environment variables.

Missing secret {#v0:schemas:missing-secret}

Code: 400

A specific secret path that was expected is not present.

How to fix:

Verify the required secret exists in your vault configuration.

Invalid parameters {#v0:schemas:invalid-parameters}

Code: 400

The parameters object in the request body is invalid (e.g., wrong type).

How to fix:

Ensure parameters is a JSON object (dict) containing at least a prompt key.

Missing parameter {#v0:schemas:missing-parameter}

Code: 400

A required configuration parameter is missing from the request.

How to fix:

Check the error message for which parameter is missing (e.g., prompt) and include it in your request.

Invalid parameter {#v0:schemas:invalid-parameter}

Code: 400

A specific configuration parameter has an invalid type or value.

How to fix:

Check the error message for the parameter path, expected type, and the value you provided.

Invalid inputs {#v0:schemas:invalid-inputs}

Code: 400

The set of input keys provided doesn't match the set of input keys expected by the prompt template.

How to fix:

Check your prompt template for {{variable}} placeholders and ensure the inputs object contains exactly those keys.

Missing input {#v0:schemas:missing-input}

Code: 400

A specific input key required by the prompt template is missing.

How to fix:

Add the missing key to your inputs object.

Invalid input {#v0:schemas:invalid-input}

Code: 400

A specific input value has an invalid type.

How to fix:

Ensure all input values are strings.

Invalid outputs {#v0:schemas:invalid-outputs}

Code: 400

The outputs provided (for evaluators) are of an unexpected type.

How to fix:

Ensure outputs are either a string or a dict.

Missing output {#v0:schemas:missing-output}

Code: 400

A required output field is missing.

Interface errors

Invalid URI {#v0:interface:invalid-uri}

Code: 400

The workflow interface URI is not recognized.

How to fix:

Ensure you're using a valid interface URI from the registry.

Workflow errors

These errors occur during the execution of built-in or custom workflows.

Prompt formatting error {#v0:workflows:prompt-formatting-error}

Code: 400

The prompt template could not be formatted with the provided inputs.

Common causes:

Template syntax errors (mismatched braces, invalid Jinja2).
Input values that cause formatting failures.

Regex pattern error {#v0:workflows:regex-pattern-error}

Code: 400

An invalid regular expression pattern was provided to a regex-based evaluator.

How to fix:

Verify your regex pattern is valid.

Prompt completion error {#v0:workflows:prompt-completion-error}

Code: 500

The LLM call failed during prompt completion.

Common causes:

The LLM provider returned an error (rate limit, server error, invalid request).
Network connectivity issues to the provider.

JSON diff error {#v0:workflows:json-diff-error}

Code: 500

The JSON diff evaluator encountered an error while comparing outputs.

Levenshtein distance error {#v0:workflows:levenshtein-distance-error}

Code: 500

The Levenshtein distance evaluator encountered an error.

Syntactic similarity error {#v0:workflows:syntactic-similarity-error}

Code: 500

The syntactic similarity evaluator encountered an error.

Semantic similarity error {#v0:workflows:semantic-similarity-error}

Code: 500

The semantic similarity evaluator encountered an error.

Custom webhook server error {#v0:workflows:custom-hook-server-error}

Code: 500

The external webhook server returned an error when called by a custom evaluator.

How to fix:

Check the logs of your webhook server.
Verify the webhook URL is correct and reachable.

Custom webhook client error {#v0:workflows:custom-hook-client-error}

Code: 500

The SDK failed to reach the external webhook server.

Common causes:

Network connectivity issues.
Invalid webhook URL.
Webhook server is down.

Custom code server error {#v0:workflows:custom-code-server-error}

Code: 500

A custom code evaluator raised an exception during execution.

How to fix:

Check the error message and stacktrace for details about the failure in your custom code.

Agent run errors

When an agent turn fails, the chat stream carries a data-agent-error part before the stream's error part:

{
  "type": "data-agent-error",
  "data": {
    "code": "rate_limited",
    "errorText": "Too many requests right now. Try again in a moment."
  }
}

Field	Description
`code`	A stable class for the failure. Key your client's behavior on it.
`errorText`	A sentence for the person in the chat. Its wording can change between releases.

The table lists the codes of the agent runtime, the service that runs the agent. The platform can also send its own codes before the runtime starts, for example agent_run_failed or a gateway code such as gateway_connection_refused; treat a code you do not know like runner_error. Show errorText for every code. For internal_error, show only errorText: the runtime withheld the underlying text on purpose, so do not replace it with a trace's error text.

Code	What happened	Retry
`runner_error`	The run failed for a reason no other code names. `errorText` says what is known.	Depends on `errorText`
`access_denied`	The user, API key or installation this run acts as may not do this in the project, for example after it was removed from the project or the key was deleted.	No: ask an owner or admin for access
`rate_limited`	The model provider or a proxy in front of it throttled the request.	Yes, after a moment
`provider_error`	The model provider refused this request with an error of its own (a content filter, a refusal, an invalid request). `errorText` quotes the provider's reason with credentials removed.	Not as is: change the request or the model
`wallet_balance_exhausted`	The organization has used all its credits. If the task was refused before it started, nothing was charged. If a call to one of Agenta's included models was refused during a task, the work before that call was charged.	No: wait for daily credits, buy credits, or upgrade. See Plans and credits
`concurrent_turns_limit`	The organization already runs as many concurrent tasks as its plan allows. The task did not start, and nothing was charged.	Yes, when another task finishes
`turn_time_limit_reached`	The task ran for the longest time its plan allows and was stopped. Saved work is kept.	Send a message to continue
`builtin_models_not_enabled`	Agenta's included models are not turned on for the organization. A model on your own API key still works.	No: use your own API key
`starter_credits_exhausted`	The organization's free Agenta credits are used up.	No: add a provider key
`starter_credits_program_paused`	Free Agenta credits are paused for everyone.	No: add a provider key
`starter_credits_unavailable`	The credits service could not be reached.	Yes, after a moment
`run_idle_time_limit`	The agent made no progress for the runtime's idle limit, so the runtime ended the turn. `errorText` names the limit, for example "The agent stopped responding: no progress for 120 seconds, so the turn was ended. Send the message again to retry."	Yes
`run_first_response_time_limit`	The model did not start to answer within the runtime's limit, so the runtime ended the turn. `errorText` names the limit.	Yes
`run_total_time_limit`	The turn ran longer than the runtime's total limit, so the runtime ended it. `errorText` names the limit.	Yes, with a smaller request
`tool_call_time_limit`	A tool call ran longer than the runtime's limit and did not stop, so the runtime ended the turn. `errorText` names the limit.	Yes, with smaller steps
`harness_init_timeout`	The harness did not answer while the run was opening its session, so nothing ran. `errorText` names the harness and the limit.	Yes
`credential_delivery_failed`	The run's model credential did not reach the model in time (a cloud sandbox race).	Yes
`subscription_login_required`	The subscription sign-in used by this connection is no longer valid. For ChatGPT, the sign-in expired or was revoked. For Claude, the provider refused the setup-token.	No: sign in to ChatGPT again, or paste a new Claude token
`subscription_login_refreshed`	Another session renewed the ChatGPT sign-in during this run.	Yes
`session_turn_in_use`	The turn was not started, because another turn already runs in this conversation, or because the platform was too busy to confirm the turn could start. Nothing ran.	Yes, once the other turn ends or after a moment
`session_admission_rejected`	The turn was not started, because the platform refused the turn's request (for example an invalid session ID or a key without access). Nothing ran.	No: fix the request first
`sandbox_gone`	The sandbox running the turn stopped answering, so the turn was ended.	Yes: a new sandbox starts
`sandbox_capacity`	The sandbox provider is at its capacity limit.	Yes, in a few minutes
`execution_lost`	The run ended without an outcome of its own (the agent service restarted or stopped answering).	Yes
`runner_capacity`	The agent service is at its session or memory limit. In-process runs only.	Yes, in a moment
`model_unavailable`	The agent's model is not available to this runtime. In-process runs only.	No: pick another model
`internal_error`	A failure the agent service does not show. `errorText` carries a reference to its log. In-process runs only.	Yes, once; report the reference if it fails again

A turn that was refused before it started does not open a stream when you call the invoke endpoint for a JSON response. The endpoint then answers with an HTTP status instead, and status.failure_code carries the code from the table:

HTTP status	`failure_code`	What happened
409	`session_turn_in_use`	Another turn already runs in this conversation.
503	`session_turn_in_use`	The platform was too busy to confirm the turn could start. The `Retry-After` header says how many seconds to wait before you send it again.
422	`session_admission_rejected`	The platform refused the turn's request.

Error response format​

Schema errors​

Invalid secrets {#v0:schemas:invalid-secrets}​

Missing secret {#v0:schemas:missing-secret}​

Invalid parameters {#v0:schemas:invalid-parameters}​

Missing parameter {#v0:schemas:missing-parameter}​

Invalid parameter {#v0:schemas:invalid-parameter}​

Invalid inputs {#v0:schemas:invalid-inputs}​

Missing input {#v0:schemas:missing-input}​

Invalid input {#v0:schemas:invalid-input}​

Invalid outputs {#v0:schemas:invalid-outputs}​

Missing output {#v0:schemas:missing-output}​

Interface errors​

Invalid URI {#v0:interface:invalid-uri}​

Workflow errors​

Prompt formatting error {#v0:workflows:prompt-formatting-error}​

Regex pattern error {#v0:workflows:regex-pattern-error}​

Prompt completion error {#v0:workflows:prompt-completion-error}​

JSON diff error {#v0:workflows:json-diff-error}​

Levenshtein distance error {#v0:workflows:levenshtein-distance-error}​

Syntactic similarity error {#v0:workflows:syntactic-similarity-error}​

Semantic similarity error {#v0:workflows:semantic-similarity-error}​

Custom webhook server error {#v0:workflows:custom-hook-server-error}​

Custom webhook client error {#v0:workflows:custom-hook-client-error}​

Custom code server error {#v0:workflows:custom-code-server-error}​

Agent run errors​

Error response format

Schema errors

Invalid secrets {#v0:schemas:invalid-secrets}

Missing secret {#v0:schemas:missing-secret}

Invalid parameters {#v0:schemas:invalid-parameters}

Missing parameter {#v0:schemas:missing-parameter}

Invalid parameter {#v0:schemas:invalid-parameter}

Invalid inputs {#v0:schemas:invalid-inputs}

Missing input {#v0:schemas:missing-input}

Invalid input {#v0:schemas:invalid-input}

Invalid outputs {#v0:schemas:invalid-outputs}

Missing output {#v0:schemas:missing-output}

Interface errors

Invalid URI {#v0:interface:invalid-uri}

Workflow errors

Prompt formatting error {#v0:workflows:prompt-formatting-error}

Regex pattern error {#v0:workflows:regex-pattern-error}

Prompt completion error {#v0:workflows:prompt-completion-error}

JSON diff error {#v0:workflows:json-diff-error}

Levenshtein distance error {#v0:workflows:levenshtein-distance-error}

Syntactic similarity error {#v0:workflows:syntactic-similarity-error}

Semantic similarity error {#v0:workflows:semantic-similarity-error}

Custom webhook server error {#v0:workflows:custom-hook-server-error}

Custom webhook client error {#v0:workflows:custom-hook-client-error}

Custom code server error {#v0:workflows:custom-code-server-error}

Agent run errors