Error Reference

Machine-readable error lookup table for all errors an agent may encounter when interacting with the Agent Registry system. Errors are grouped by source: smart contract reverts, relayer HTTP errors, and REST API errors.

Contract Reverts (Agentenregister)

These errors are raised by the Agentenregister.sol smart contract. When using the gasless relayer, they appear in the relayer's HTTP 500 response body. When using direct transactions, they appear as transaction revert reasons.

Error Message	Source Function	Cause	Resolution
"Only owner"	onlyOwner modifier	Caller is not the contract owner	Use the owner wallet. This is an admin-only function.
"Only regulator"	onlyRegulator modifier	Caller is not a regulator or the owner	Contact the registry administrator to perform this action.
"Not authorized for this agent"	onlyAgentOrCreator modifier	Caller is not the agent's wallet, creator, or Haftungsperson	Sign the transaction with the correct private key (agent wallet, creator wallet, or Haftungsperson wallet).
"Agent not found"	agentExists modifier	The agentId does not exist in the registry	Verify your agent ID. Query /api/v1/agent/:id or call getAgent(agentId) to check.
"Agent not active"	agentActive modifier	The agent's status is Suspended, Revoked, or Terminated	Check status with complianceStatus(agentId). Suspended agents can be reactivated by a regulator. Revoked/Terminated agents cannot be restored.
"Parent agent not found"	registerAgent	The parentAgentId passed to registration does not exist	Verify the parent agent ID. Use 0 for root agents (no parent).
"Parent agent not active"	registerAgent	The parent agent is not in Active status	The parent must be Active to spawn children. Contact a regulator if it is Suspended.
"Max generation depth exceeded"	registerAgent	The child agent would exceed the maximum generation depth (default: 10)	The lineage tree cannot go deeper than 10 generations. Restructure your agent hierarchy.
"Wallet already registered to another agent"	registerAgent	The agentWallet address is already associated with another agent	Generate a new Ethereum key pair (Step 1) and use the new address.
"Only suspended agents can be reactivated"	reactivateAgent	Attempted to reactivate an agent that is not in Suspended status	Only Suspended agents can be reactivated. Active agents do not need reactivation. Revoked and Terminated agents cannot be reactivated.
"No agent registered for this wallet"	getAgentByWallet	No agent is associated with the queried wallet address	The wallet has not been used to register an agent. Verify the address.

Contract Reverts (MinimalForwarder)

These errors are raised by the MinimalForwarder.sol contract during meta-transaction verification and execution.

Error Message	Source Function	Cause	Resolution
"MinimalForwarder: invalid signature"	execute	The EIP-712 signature does not match the request data, or the nonce is incorrect, or the deadline has passed	1. Re-fetch the nonce from GET /nonce/:address. 2. Verify the chain ID matches (84532 for Base Sepolia). 3. Ensure the from field matches the signing wallet. 4. Check that the data field was not modified after signing.
"MinimalForwarder: invalid signature length"	_splitSignature	The signature is not exactly 65 bytes	Ensure the signature is a valid ECDSA signature (r: 32 bytes + s: 32 bytes + v: 1 byte = 65 bytes). Check your signing library output.

Relayer HTTP Errors

These errors are returned by the gasless relayer service (relayer/relayer.js) as JSON responses.

HTTP Status	Error Message	Cause	Resolution
400	"Missing request or signature"	The POST body is missing the request or signature field	Include both request (object) and signature (hex string) in the JSON body.
401	"Invalid signature or nonce mismatch"	The relayer verified the signature on-chain and it failed	1. Re-fetch the nonce from GET /nonce/:address. 2. Re-sign the request with the updated nonce. 3. Verify chain ID and forwarder address match the relayer's domain.
403	"Relayer only forwards to the Agentenregister contract"	The request.to field is not the registry contract address	Set request.to to 0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23. The relayer only forwards to the Agentenregister.
403	"Value transfers not supported"	The request.value field is greater than 0	Set request.value to "0". The relayer does not forward ETH value.
429	"IP rate limit exceeded (20/hour)"	Too many requests from the same IP address within one hour	Wait for the rate limit window to reset (up to 1 hour). Default limit: 20 requests per IP per hour.
429	"Signer rate limit exceeded (10/hour)"	Too many requests from the same signer address within one hour	Wait for the rate limit window to reset (up to 1 hour). Default limit: 10 requests per signer per hour.
429	"Daily gas budget exhausted. Try again tomorrow."	The relayer has spent its entire daily gas budget	Wait until the daily budget resets (24 hours from first use). Alternatively, switch to direct mode (agent pays gas). Check GET /status for budget remaining.
503	"Relayer balance too low. Please try again later or use direct mode."	The relayer wallet has less than 0.001 ETH	The relayer needs to be refunded. Try again later or switch to direct transaction mode.
500	(various)	An unexpected error occurred during relay execution	Check the error message for details. Common causes: contract revert (see contract errors above), RPC timeout, or network issues.

REST API Errors

These errors are returned by the read-only REST API (api/server.js).

HTTP Status	Error Message	Cause	Resolution
404	"Agent not found: ..."	The requested agent ID does not exist in the registry	Verify the agent ID. Use GET /api/v1/stats to check the total number of registered agents.
429	"Rate limit exceeded. Try again in 1 minute."	More than 60 requests per minute from the same IP	Wait 1 minute for the rate limit to reset. The API allows 60 requests per minute per IP.
500	(various)	Internal server error (RPC failure, contract call failure)	Retry after a short delay. If persistent, check that the API server's RPC connection is healthy via GET /health.

Diagnostic Endpoints

Use these endpoints to diagnose issues:

Endpoint	Service	What It Returns
GET /status	Relayer (port 3001)	Relayer wallet balance, daily gas budget used/remaining, contract addresses
GET /health	API (port 3000)	API health status, registry address, RPC URL
GET /nonce/:address	Relayer (port 3001)	Current nonce for the given address (for building the next request)
GET /domain	Relayer (port 3001)	EIP-712 domain parameters (name, version, chainId, verifyingContract)

Troubleshooting Flowchart

Error occurred
│
├── HTTP 4xx from relayer?
│   ├── 400 → Check request body format
│   ├── 401 → Re-fetch nonce, re-sign
│   ├── 403 → Check `to` address and `value`
│   └── 429 → Wait for rate limit reset
│
├── HTTP 503 from relayer?
│   └── Relayer out of funds → Wait or use direct mode
│
├── HTTP 500 from relayer?
│   └── Check error message → Likely a contract revert
│       ├── "Agent not found" → Wrong agent ID
│       ├── "Agent not active" → Agent suspended/revoked
│       ├── "Not authorized" → Wrong signing key
│       └── "invalid signature" → Nonce/chainId/signing error
│
├── HTTP 4xx from API?
│   ├── 404 → Agent ID does not exist
│   └── 429 → Rate limited, wait 1 minute
│
└── Transaction reverted on-chain?
    └── Decode revert reason from transaction receipt
        └── Match against contract error table above