Errors & Troubleshooting

Start here

Symptom	First check
The tool asks for confirmation	Confirm deliberately — see Confirmations & Spend Safety
You are asked to sign in again	Re-authenticate; if it repeats immediately, check Agent Access
Permission denied	The connecting user's Orders permissions
Too many changes too quickly	Wait briefly, then retry
A purchase is refused over money	Wallet balance and the agent spend limit
A status change is refused	Order Statuses
The Label is not ready	Wait and ask for the Label again
A Label purchase is already in progress	Wait, then read the current Label state
Something failed unexpectedly	Read the current state before repeating any change

Two ways a call can fail

The connection or authorization failed, and no tool ran. Nothing in Mailhub was attempted. Sign-in, Agent Access, and OAuth failures land here.

A tool ran and returned a refusal. The call itself succeeded at the protocol level and the payload carries an errors array. Everything else on this page is this second kind.

A successful call returns the tool's own data. A refusal returns an error envelope:

{
  "errors": [
    {
      "code": "MCP_INVALID_UUID",
      "message": "..."
    }
  ]
}

• code is the machine-readable part. Branch on it.
• message is the human-readable part. It often carries the specific detail — which field was missing, which statuses are reachable, which status an Order should resume to.
• errors can hold more than one entry. Read them all; the first is not guaranteed to be the only problem.

A failed action can arrive as a successful tool result

Inspect the returned payload for errors. A Mailhub business or guardrail failure can be returned as a normal MCP tool result containing an error envelope, so a client that checks only a protocol-level error flag will read a refusal as a success. The payload is the source of truth for whether the Mailhub action happened.

Input and confirmation errors

Code	Meaning	Retry?	What to do
MCP_CONFIRMATION_REQUIRED	A changing tool was called without confirmation	Yes, after deliberately confirming	Review the change, then call again with confirm as the JSON boolean true
MCP_INVALID_UUID	An identifier is not a valid UUID	Not with the same value	Look the Order, Shipment, or Label up again and use the identifier Mailhub returned
MCP_MISSING_FIELD	A required field is missing or blank	After fixing the input	Supply the field the message names
MCP_INVALID_VALUE	A value is outside the accepted set	After correcting the value	Use one of the names the message lists — for statuses, see Order Statuses

The confirmation rule is exact: only the JSON boolean true confirms a change. See Confirmations & Spend Safety.

Authentication, Agent Access, and permissions

You are asked to authenticate again

Some failures surface as a re-authentication request rather than as a tool error. Re-authenticating the connector is the right first move.

Signing in again is not always the real problem

If re-authenticating immediately leads to the same failure, verify that Agent Access is enabled for the account and that the connecting Mailhub user is still active and has access to that account. Agent Access being off, and a user who has lost access to the account, both produce the same "sign in again" symptom as an expired session — and no amount of re-authenticating fixes either. See Authentication and Before You Connect.

Code	Meaning	Retry?	What to do
MCP_ACCOUNT_UNRESOLVED	Mailhub cannot resolve the account a changing call belongs to	After re-authenticating	Reconnect and authorize again; if it persists, contact Developer Support

Permission denied

Permission failures come back through the Mailhub error envelope rather than under an MCP_-prefixed code. Check what the connecting user actually holds:

• Listing Orders, reading one, and getting a Label link need view access to Orders.
• Getting Rates needs update access, even though it changes nothing.
• Creating, changing status, buying, and cancelling need update access.

Agent Access is a separate account-level gate on top of those permissions — having the permission is not enough if the account has agents switched off.

Not found, or not yours

A resource that does not exist and a resource your account may not see are answered the same way. Mailhub does not reveal that something exists in another account. Re-read the identifier from mailhub_list_orders or mailhub_get_order before assuming it is a bug.

Rate and spend controls

Code	Meaning	Retry?	What to do
MCP_WRITE_RATE_LIMITED	The account hit the guard on changing MCP calls	Yes, after a short wait	Slow down and retry shortly
Wallet.InsufficientFunds	The wallet balance does not cover the purchase	Only once the wallet is funded	Fund the account in Mailhub — MCP has no top-up tool
Wallet.McpSpendCapExceeded	The purchase would exceed the rolling 24-hour agent spend limit	Not immediately	Wait for older spend to leave the window, or have an authorized account user change the limit
Wallet.DebitFailed	The wallet debit could not complete, typically because the balance changed at the same moment	Yes, once you have checked the state	Re-read the Order and Label state first, then decide whether the purchase still needs to be made

Mailhub currently targets a guard of about 10 changing MCP calls per minute per account; it is a request-rate guard, not a spend quota. An assistant cannot raise its own spend limit. Both controls are covered in Confirmations & Spend Safety.

Order and status errors

Every refused status change returns one code:

Code	Meaning	Retry?	What to do
Order.StatusTransitionNotAllowed	The status change was refused	Only with a target the Order accepts	Read the message — it says which case this is and what to do next

There is no second code to branch on

The cases below are told apart by the message, not by the code. All of them arrive as Order.StatusTransitionNotAllowed. A client that branches on invented per-case codes will match none of them and fall through on every refusal.

The message says	Retry?	What to do
The Order is already in that status	No	Nothing to do — carry on from the current status
The transition is not allowed, and names the statuses the Order can move to	Only with one of those targets	Pick a status the message lists
LabelCreated is set when a Label is purchased	Not as a status update	Buy a Label with mailhub_buy_label — that is what sets it
An Order with a purchased Label returns to Packed only by cancelling that Label	No	Cancel the Label instead — that is what returns the Order
The Order cannot be cancelled directly; cancel its Label first	Not until the Label is gone	Cancel the Label, let the Order return to Packed, then cancel the Order
A draft Order's status cannot be set directly	No	Leave Draft alone; saving or buying is what moves a draft on
The Order was put on hold from a named status — resume it to that one	Only with that target	Resume to the status the message names

Order Statuses has the full model behind every one of these.

Order detail errors

Code	Meaning	Retry?	What to do
MCP_ORDER_DETAILS_UNAVAILABLE	Mailhub cannot resolve usable Shipment detail for that Order	Not by repeating the same call	Check the Order identifier with mailhub_list_orders; the Order may be a Draft or may have no Shipment to read
MCP_ORDER_DETAILS_UNREADABLE	Mailhub could not read the Order detail needed for the Label link	Once	Try once more; if it persists, contact Developer Support

Label purchase conflicts

Two different families refuse a purchase. The Order's state refuses under Order.*; a competing purchase refuses under LabelPurchase.*.

The Order's state:

Code	Meaning	Retry?	What to do
Order.LabelPurchaseBlockedByHold	The Order is on hold	After resuming the Order	Resume the Order to the status the message names, then buy
Order.LabelPurchaseBlockedByFulfilment	The Order was already handed to the carrier	No	A fulfilled Order does not take a new Label
Order.LabelPurchaseBlockedByReturn	The Order has been returned	No	A returned Order does not take a new Label
Order.CarrierSelectionNotAllowed	The Order is cancelled, so no carrier can be selected for it	No	Nothing is buyable on a cancelled Order
Order.LabelAlreadyPurchased	The Order already holds a Label	Not until that Label is gone	Cancel the existing Label first if it is being replaced

A competing purchase on the same Shipment:

Code	Meaning	Retry?	What to do
LabelPurchase.InProgress	A different Label purchase is already running for that Shipment	Only after it settles	Wait, then read the Order and Label state before starting anything else
LabelPurchase.OutcomeUnresolved	Mailhub is still resolving an uncertain carrier outcome	Later, not immediately	Wait, then check the Order and Label state
LabelPurchase.ConcurrentAdmission	Two purchase attempts raced each other	Yes	First check whether one of them became active or completed, then retry if a Label is still needed
LabelPurchase.LabelCancelled	The Label bought by this request was cancelled before its result came back	No — terminal for that purchase	If a Label is still needed, start a fresh Rates and purchase workflow deliberately

Repeating the same Shipment and Rate is safe and will not buy a second Label. That protection covers Label purchase only — it does not make the other changing tools safe to repeat. See Working with Labels.

Label readiness errors

Code	Meaning	Retry?	What to do
MCP_LABEL_NOT_READY	The Label file is still being generated	Yes — the normal wait	Wait a few seconds and request the Label link again
MCP_LABEL_NOT_PURCHASED	No Label has been bought for that Shipment	Only after buying	Get Rates and buy a Label first
MCP_LABEL_CANCELLED	The Label was cancelled	No — terminal for that Label	Buy a new Label if one is still needed
MCP_LABEL_ERROR	The Label failed during generation	No — waiting does not help	Buy a new Label for the Shipment; contact Developer Support if it keeps failing
Label.AssetsUnavailable	The Label was bought, but its file cannot be produced	No — repeated attempts are not expected to fix it	Do not buy another Label; contact Developer Support with the Order and Shipment

MCP_LABEL_NOT_READY is the one worth retrying. The others describe a Label that will never become downloadable, so repeating the request only delays the purchase that is actually needed.

Label.AssetsUnavailable is different again: the purchase succeeded and the money was spent, so buying a replacement is the wrong move — the Label needs recovering, not repurchasing.

OAuth authorization errors

These appear while connecting, before any tool runs.

Error	Meaning	What to do
access_denied	Authorization was declined	Start authorization again only if access is actually intended
insufficient_scope	The authorization does not carry the scope MCP needs	The required scope is mcp.tools; use the registered Mailhub MCP client configuration
invalid_redirect_uri	The client's callback is not one Mailhub accepts for this client	Do not guess another callback — use a Mailhub-supported client, and contact Developer Support if it should be supported
invalid_target	The MCP resource requested does not match what the client is registered for	Check that the supported client is pointed at the right Mailhub environment; contact Developer Support if it persists
invalid_request	The client's request does not match its allowed OAuth configuration	Use the supported client setup; contact Developer Support
unsupported_grant_type	The client tried a grant Mailhub MCP does not support	Mailhub supports Authorization Code, with Refresh Token for renewal

Authentication covers the flow these belong to.

Temporary and unexpected failures

A call can also fail without a business reason — a timeout, or a response Mailhub could not return properly. These arrive under their own codes:

Code	Meaning	Retry?	What to do
MCP_MALFORMED_ENVELOPE	Mailhub's response could not be read	A read, yes; a change, only after checking state	The message says only that the response was empty or unreadable — there is no business detail to act on
MCP_UNKNOWN_ERROR	Mailhub reported a failure but named no reason	A read, yes; a change, only after checking state	Read the current state before repeating anything that changes data

Neither carries a specific cause. Treat them by what the call was doing:

• A read can simply be retried after a short wait.
• A change must not be blindly repeated. Read the current state first, then decide.

What "read the state first" means per tool:

After an uncertain…	Do this before anything else
mailhub_create_order	List Orders and look for the one you may have created
mailhub_update_order_status	Read the Order — a repeat that already applied is refused as already in that status
mailhub_buy_label	Check the Order and Label state; repeating the same purchase is safe, starting a different one is not
mailhub_cancel_label	Re-read the Order and Label; repeating a cancellation is safe

If an unexpected failure repeats, contact Developer Support rather than retrying indefinitely.

Next

If a failure persists after the action its row names, raise it through the support arrangement in place for your account — Developer Support explains what to include.

• What a confirmed change still has to clear: Confirmations & Spend Safety.
• Which status changes are allowed: Order Statuses.