Errors Related to Agents
This guide explains the errors that may occur when interacting with Mailbox and Proxy Agents as well as message envelopes. Errors are raised when validation fails, when an Agent cannot be found, when quotas or subscriptions are exceeded, or when mailbox operations are invalid. The system communicates these issues through standard HTTP exceptions with descriptive messages.
To ensure uninterrupted interaction with your agent mailboxes, it is required that users maintain an active Agentverse subscription. On the free tier, this simply means logging in to Agentverse at least once every 30 days. Failure to do so will result in your Agent’s mailbox being deactivated. This mechanism ensures efficient resource management and prevents unmaintained Agents from consuming unnecessary resources.
Ensure you log in at least once every 30 days to prevent your hosted Agent from being deactivated.
Envelope Validation Errors
Submitting an envelope to /v1/submit first triggers a verification step. If the envelope cannot be validated, the API returns a 400 Bad Request:
This ensures that malformed or tampered envelopes are rejected immediately.
Agent Lookup Errors
Agent existence is checked in multiple places. When submitting a message to an Agent that does not exist with POST /v1/submit, a 404 is raised with:
When probing readiness with HEAD /v1/submit, the x-uagents-address header must be provided. If it is missing, a 400 Bad Request is raised with:
Quotas and Subscriptions Errors
The system enforces quotas for messages, storage, and data transfer, checked against either legacy plans or the newer subscription model. A quota is simply a limit. Each user and their agents are bound by message, storage, and transfer quotas. On the other hand, a subscription represents whether the user is on an active plan or not. In short, quotas are about how much a user is allowed to use, while subscriptions are about whether the user is still allowed to use the service at all.
If a user sends more messages than their plan allows, the API raises a 406 Not Acceptable error with the message:
X and Y represent the usage compared to the limit. For instance, if a user has sent 120 messages but their plan only allows 100, then the message will be “Message quota reached 120 / 100”.
Similarly, if the total stored bytes for a user go over the storage limit, the API raises 406 with:
When retrieving messages, if the total data transferred exceeds the transfer limit, the API raises 406 with:
Within the subscription system, every plan also has an expiry date. If a request is made after the plan has expired, the API responds with a 406 Not Acceptable and the message:
even if no quota has been exceeded.
Mailbox Operations Errors
Listing mailbox messages at /v1/mailbox requires both offset and limit pagination parameters. If either is missing, the API raises a 400 Bad Request:
When retrieving or deleting a specific envelope at /v1/mailbox/{uuid}, if the envelope does not exist for the given Agent, a 404 Not Found is raised:
Proxy Agent Lookup Errors
After validation, the system looks up the target proxy Agent. If no matching proxy agent is found, the API returns a 404 Not Found:
This indicates that the envelope target does not correspond to any registered Proxy Agent.