Error Codes Reference

Error Response Format

All error responses from the API use a consistent JSON structure:

{
  "error": {
    "code": "AGENT_BUDGET_EXCEEDED",
    "message": "Task exceeded configured token budget of 50000 tokens (used: 52341)",
    "detail": {
      "budget": 50000,
      "used": 52341,
      "task_id": "task_abc123"
    },
    "docs_url": "https://openclaw.ai/reference/error-codes/#agent_budget_exceeded"
  }
}

Agent Errors (1xxx)

LLM Provider Errors (2xxx)

Tool Errors (3xxx)

Configuration Errors (4xxx)

Authentication and Authorization (5xxx)

Handling Errors in Application Code

When calling the OpenClaw API from your application, handle errors by checking the error code and taking appropriate action per error class. Not all errors warrant the same response — a rate limit error should trigger a backoff and retry, while an auth error should surface to the user immediately rather than retrying:

import time
import httpx

def run_task_with_retry(task: str, max_retries: int = 3) -> dict:
    for attempt in range(max_retries):
        response = httpx.post("/v1/tasks", json={"task": task})
        if response.status_code == 200:
            return response.json()
        error = response.json().get("error", {})
        code = error.get("code", "")
        if code == "LLM_RATE_LIMITED":
            wait = 2 ** attempt   # exponential backoff
            time.sleep(wait)
            continue
        if code in ("AUTH_MISSING_KEY", "AUTH_INVALID_KEY"):
            raise ValueError(f"Authentication failed: check your API key")
        raise RuntimeError(f"Task failed: {code} — {error.get('message')}")
    raise RuntimeError("Max retries exceeded")

The docs_url field in every error response links to this reference page with the section anchored to the specific error code — your error handling code can surface this URL directly to developers investigating failures.

Task Status vs. Error Responses

Note that agent errors (AGENT_* codes) result in HTTP 200 responses with a status: "failed" field in the task result — the task ran but the agent could not complete it. These are not HTTP errors; the API call itself succeeded. HTTP error codes (4xx, 5xx) occur only for infrastructure-level failures: invalid requests, authentication failures, server errors. Always check both the HTTP status code and the task status field when determining whether a task completed successfully.

Error Codes in Logs

Every task failure in the logs includes the error code as a structured field: "error_code": "AGENT_MAX_STEPS". This makes it trivial to write log-based alerts on specific error types (alert on any LLM_AUTH_FAILED log event) and to query for failure distributions (what percentage of failures are budget-exceeded vs. LLM errors vs. tool errors?). Build a Grafana dashboard showing error code distribution over time — seasonal patterns often emerge that guide configuration tuning: if Monday mornings see more AGENT_TIMEOUT errors, it may indicate peak load requiring more concurrency.

Self-Healing Behavior

Several error conditions trigger automatic self-healing behavior rather than immediate failure. When LLM_RATE_LIMITED occurs, OpenClaw waits the duration specified in the provider's Retry-After header and then retries — up to the configured llm.max_retries times. When a tool produces a TOOL_EXECUTION_FAILED result, the agent receives the error description and can choose to retry with different arguments or try an alternative approach, rather than failing immediately. This resilience to transient errors is a key design property of the ReAct loop — it enables agents to recover gracefully from the kinds of errors that real production environments regularly produce.

Error Monitoring Best Practices

Track error code distributions in your monitoring system. A sudden spike in LLM_RATE_LIMITED suggests your traffic has grown beyond your current tier — contact your LLM provider for a quota increase before it impacts users. A steady accumulation of AGENT_MAX_STEPS on specific task types indicates those tasks need a refined system prompt or a higher max_steps value. TOOL_PERMISSION_DENIED in production is almost always a configuration mistake — the allowed_dirs or allowed_domains list wasn't updated when a new tool or task pattern was added. Investigate and resolve it immediately rather than expanding permissions blindly.