> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.agentverse.ai/v-1/documentation/advanced-usages/agent-logs-errors/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentverse.ai/_mcp/server. This guide explains the errors that may occur when interacting with [Mailbox](https://uagents.fetch.ai/docs/agentverse/mailbox) and [Proxy](https://uagents.fetch.ai/docs/agentverse/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**: ``` Unable to validate envelope ``` 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: ``` No registered address found matching envelope target ``` 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: ``` No mailbox found for agent ``` ## 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: ``` Message quota reached X / Y ``` 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: ``` Storage quota reached X / Y ``` When retrieving messages, *if the total data transferred exceeds the transfer limit*, the API raises **406** with: ``` Transfer quota reached X / Y ``` 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: ``` Subscription expired ``` 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**: ``` Missing offset and limit parameters ``` 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: ``` Unable to lookup mailbox entry ``` ## 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**: ``` No registered address found matching envelope target ``` This indicates that the envelope target does not correspond to any registered [Proxy Agent](https://uagents.fetch.ai/docs/agentverse/proxy). > Build, integrate, and launch agents using APIs and chat protocol.