The shape
Every error response from our runtime has the same JSON body:Full catalog
404 / 400
When: the tool doesn’t exist, belongs to another tenant, or has been deleted (a deleted tool is filtered out and reads as not-found, not “inactive”). This is a common symptom of a stale agent config that still references a tool you removed. Also returned at HTTP 400 when the request arrives with a missing
tenant_id or tool_id.error_message: Tool not found.llm_message: I couldn’t find that lookup. Let me continue.Fix: Check the tool still exists, isn’t deleted, and is on the same tenant as the agent.404
When: the tool exists but its
is_active flag is off. That’s the only trigger, a deleted tool returns HTTP_TOOL_NOT_FOUND instead.error_message: Tool is disabled.llm_message: That lookup isn’t currently available.Fix: Re-enable the tool in the manager.403
When: the tenant doesn’t have the Power Tools add-on active.error_message: Power Tools add-on is not active for this tenant.llm_message: Custom lookups aren’t enabled here.Fix: Add the Power Tools add-on under Account → Billing. The tool descriptor is also hidden from the agent’s tool list, so the LLM shouldn’t even try, if it does, the runtime fails closed.
400
When: the LLM called the tool with arguments that don’t match
parameters_schema. The LLM usually corrects itself and tries again.error_message: Arguments don’t match the tool’s schema: <field>: <message>.llm_message: Let me try those arguments differently.Fix: If you see this code firing repeatedly, your description is probably leading the LLM into an invalid shape. Tighten the description or relax the schema.502
When: SSRF guard rejected the URL at invocation time, usually DNS rebinding (host validated fine at save, now resolves to a private IP). See Security restrictions.error_message: URL resolves to a blocked network.llm_message: I couldn’t reach that lookup target.Fix: Check what your hostname resolves to. If you genuinely run on a public IP and we still block, open a support ticket with the resolved IP.
504
When: the full request (TLS handshake + DNS + your server + response) exceeded 10 seconds.error_message: Endpoint timed out after 10s.llm_message: Lookup timed out. Let me continue without it.Fix: Profile your endpoint. Aim for sub-2-second responses for the smoothest call experience. If you need longer-running work, return a “still processing” hint and have the AI ask the caller to hold.
502
When: DNS resolution failed, TCP connection refused, TLS handshake failed, or the connection dropped mid-stream.error_message: Couldn’t connect to endpoint:
<reason>.llm_message: I couldn’t reach the lookup service.Fix: Verify your endpoint is up. Check TLS certificate validity (expired certs are a common cause). Confirm DNS resolves correctly from the public internet.502
When: your endpoint returned a 3xx redirect. We don’t follow redirects, your URL must resolve directly to the handler.error_message: Endpoint redirected too many times.llm_message: The lookup service is misconfigured. Continuing without it.Fix: Resolve the final URL yourself and update the tool’s endpoint to point straight at it.
502
When: your endpoint returned
application/octet-stream or another binary content type.error_message: Endpoint returned unsupported content-type: <ct>.llm_message: Lookup returned an unsupported format.Fix: Return application/json or any text/* content type. The AI can’t speak binary blobs.200
When: your response body exceeded 64 KB. This is not a hard error, we truncate and still pass the first 64 KB to the AI with a
[truncated] footer. It’s flagged in the invocations log so you know.error_message: Response was N bytes; truncated to 65536.llm_message: Lookup returned a large response; I’ll work with the first part.Fix: Design responses to fit in 4 KB ideally. The AI doesn’t summarize huge blobs reliably.502
When: your endpoint returned a 4xx or 5xx status code.error_message: Endpoint returned
<status>.llm_message: The lookup service returned an error. Continuing.Fix: Check your endpoint logs. Often this means your auth check failed (the Bearer token in the tool config doesn’t match what your server expects) or your code path hit an unhandled exception.429
When: the per-tenant (60/min) or per-tool (30/min) token bucket has emptied. See Rate limits.error_message: Rate limit exceeded (60/min tenant) or (30/min for this tool).llm_message: I’ve used lookups too many times recently. I’ll work with what I have.Fix: This is a soft limit, your call doesn’t crash, the AI just stops calling the tool for a bit. If you legitimately need more, open a ticket and we’ll raise your quota.
Each error code links to its docs
Everyerror_code in the dashboard’s Invocations panel is a clickable link straight to the matching anchor on this page (e.g. #http-tool-rate-limited). So when you grep your invocation logs and see HTTP_TOOL_TIMEOUT, one click gets you to a fix.
Next: Rate limits
Token-bucket spec for the per-tenant and per-tool budgets.