Error Codes - AgentRegistry

HTTP Status Codes

2xx Success

Code	Response	When
`200`	OK	Package metadata retrieved, tarball downloaded, stats returned
`201`	Created	Package published successfully
`204`	No Content	OPTIONS preflight, successful deletion

4xx Client Errors

Code	Error	Cause	Solution
`400`	Bad Request	Invalid JSON, missing required fields, malformed tarball name	Check request body format and required fields
`401`	Unauthorized	Missing or invalid admin token	Use token from admin panel or X-Admin-Token header
`403`	Forbidden	Security scan blocked package, IP not allowed	Check quarantine or allowlist settings
`404`	Not Found	Package doesn't exist locally or upstream	Verify package name and version
`409`	Conflict	Version already exists	Bump version before publishing again
`429`	Too Many Requests	Rate limit exceeded (1000 req/min)	Wait and retry, or check for runaway scripts

5xx Server Errors

Code	Error	Cause	Solution
`500`	Internal Server Error	Invalid package name, path traversal attempt, server bug	Check server logs, verify input validation
`502`	Bad Gateway	Upstream npmjs.org unreachable or returned error	Check internet connection, retry later

Error Response Format

All errors return JSON with consistent structure:

{
  "error": "Not Found",
  "message": "Package 'my-package' does not exist"
}

Security Block Response

When a package is blocked by security scanning:

{
  "error": "Package blocked by security scan",
  "package": "suspicious-pkg@1.0.0",
  "action_required": "HUMAN INTERVENTION REQUIRED",
  "instructions": [
    "The package has been quarantined for manual review",
    "Open the admin panel to inspect the security issues",
    "If safe, approve the package manually"
  ],
  "admin_url": "http://localhost:4873/-/admin",
  "quarantine_path": "storage/quarantine/suspicious-pkg-1.0.0.tgz"
}

WebSocket Errors

Type	Message	Cause
`error`	`{ message: "Invalid action" }`	Unknown action type sent
`error`	`{ message: "Missing parameter: X" }`	Required payload field missing
`error`	`{ message: "Invalid IP pattern" }`	Malformed CIDR or wildcard pattern

Common Issues

❓ "Cannot find package" but it exists on npm

The package might be blocked in quarantine. Check Admin Panel → Quarantine tab.

❓ "Rate limit exceeded" during tests

Wait 60 seconds for the rate limit window to reset, or increase RATE_LIMIT_MAX_REQUESTS in config.ts.

❓ "EPERM: operation not permitted"

File permission issue on macOS. Fix: Use agentregistry publish (resilient mode) or run agentregistry doctor to diagnose.

❓ WebSocket disconnects immediately

Invalid or missing token. The token is auto-injected when accessing /-/admin directly.

⚠️ Error Codes