Error Handling

Error response format


{
  "jsonrpc": "2.0",
  "error": {
    "code": -32010,
    "message": "Agent not found: unknown-agent",
    "data": {
      "agentId": "unknown-agent",
      "suggestion": "Use GET /v1/a2a/agents to list available agents"
    }
  }
}

Error codes

Code	Constant	Description	Retryable
`-32700`	`PARSE_ERROR`	Invalid JSON	No
`-32600`	`INVALID_REQUEST`	Malformed JSON-RPC request	No
`-32601`	`METHOD_NOT_FOUND`	Unknown JSON-RPC method	No
`-32602`	`INVALID_PARAMS`	Invalid method parameters	No
`-32603`	`INTERNAL_ERROR`	Server-side error	Yes (with backoff)
`-32001`	`TASK_NOT_FOUND`	Task ID does not exist	No
`-32002`	`TASK_NOT_CANCELABLE`	Task in terminal state	No
`-32010`	`AGENT_NOT_FOUND`	Agent slug/ID not found	No
`-32011`	`AGENT_DISABLED`	Agent is disabled	No
`-32012`	`UNAUTHORIZED`	Invalid or expired token	No (re-auth required)
`-32013`	`FORBIDDEN`	Insufficient capabilities	No
`-32014`	`QUOTA_EXCEEDED`	Rate limit or budget exceeded	Yes (after backoff)
`-32015`	`CROSS_TENANT_REJECTED`	Cross-tenant invocation without consent	No
`-32016`	`SKILL_NOT_AUTHORIZED`	Token not scoped for requested skill	No

Retry guidance

The SDK handles retries automatically for retryable errors (-32603, -32014). For manual implementations:


async function invokeWithRetry(request: InvokeRequest, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fetch('/v1/a2a/invoke', { body: request });
    } catch (err) {
      if (!isRetryable(err) || attempt === maxRetries) throw err;
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}
 
function isRetryable(err: JsonRpcError): boolean {
  return [-32603, -32014].includes(err.error.code);
}