Errors

Errors use a consistent envelope.

{
  "error": {
    "code": "validation_failed",
    "message": "Input is invalid.",
    "details": [
      {
        "field": "input.vendor",
        "code": "required",
        "message": "Vendor is required."
      }
    ],
    "requestId": "req_123"
  }
}

requestId is included when the request sends X-Request-Id.

Common errors

HTTP status	Code	Meaning
`400`	`validation_failed`	Request body is invalid.
`400`	`lane_required`	The agent has multiple lanes and the request did not include `laneId`.
`400`	`lane_not_supported`	The requested `laneId` is not public for this agent.
`400`	`message_required`	A chat lane run is missing `input.message`.
`400`	`message_too_long`	A chat lane run has `input.message` longer than 20,000 characters.
`401`	`missing_api_key`	Missing bearer token.
`401`	`invalid_api_key`	The bearer token is not a valid Erstan API key.
`401`	`api_key_revoked`	The key was revoked.
`401`	`api_key_expired`	The key has expired.
`401`	`api_key_user_inactive`	The user who created the key no longer belongs to the workspace.
`403`	`scope_denied`	The key does not have the required scope.
`403`	`agent_not_published`	The agent is not published.
`403`	`agent_disabled`	The agent is disabled.
`404`	`agent_not_found`	The agent is not visible to the key.
`404`	`run_not_found`	The run was not started by this key or does not exist.
`429`	`rate_limited` or surface-specific message	Request budget or provider capacity is exhausted; honor retry timing.
`500`	`internal_error`	Unexpected server error.

Throttling middleware and hosted MCP can return a different envelope from ordinary public API errors. Check HTTP status and Retry-After first. See Rate limits for the current budgets, queued Agent behavior and safe retry guidance.

Developer API

JavaScript SDK (beta)

Partners

API Reference

Common errors

​Common errors

Common errors