Agent creation returns opaque HTTP 429 with no reset or quota guidance

[notforhumansfun-rgb]

Virtuals ACP agent creation returns an opaque HTTP 429

Prepared: 2026-08-23. This report contains no access token, refresh token, private key, signer key, or wallet secret.

Published upstream: #92

Summary

An authenticated Virtuals account can list its existing agents, but creating one additional zero-signer agent consistently returns:

HTTP 429: {"statusCode":429,"message":"Rate limit exceeded"}

The attempts were separated across continuation windows; this was not a tight retry loop. No agent or service wallet was created.

Environment

• package: @virtuals-protocol/acp-cli@1.0.33
• audited repository commit: b7d478f7875eb913b4b25e92dcf7ee6b5ab00238
• platform: macOS arm64
• authentication: split browser flow completed successfully
• read-only acp agent list: succeeds
• existing agents on account: 2
• requested signer at creation: none
• image: omitted

Reproduction

acp agent create \
  --name 'TIDE / NOT FOR HUMANS #8061' \
  --description 'Independent read-only evidence and reconciliation oracle for FLUX.' \
  --json

Expected

The CLI creates one HYBRID agent and returns its agent ID and dedicated wallet, or returns a documented quota with a reset time and remediation path.

Actual

The API returns an opaque 429 Rate limit exceeded. The CLI's ApiClient.post() throws only the HTTP status and response body. It does not preserve Retry-After, expose rate-limit headers, or implement backoff.

Source audit

• AgentApi.create() sends { name, description, role: "HYBRID" } to POST /agents.
• The command does not create a signer unless --signer is explicitly supplied.
• The public README documents agent creation but no account quota or retry interval.
• The official repository issue list contained no matching agent-creation rate-limit report when checked on 2026-08-23.

Questions for Virtuals

1. Is POST /agents limited by time, IP, authenticated account, or maximum agent count?
2. What is the reset interval or account remediation path?
3. Does the API emit Retry-After or X-RateLimit-* headers that the CLI should surface?
4. Is two existing agents the intended account limit?
5. Can a failed request consume or extend the limit?

Safety impact

Deployment is intentionally stopped before signer creation, Arena registration, funding, or execution. Repeated blind retries are avoided because the reset behavior is undocumented.