[{"data":1,"prerenderedAt":561},["ShallowReactive",2],{"docs-\u002Fdocs\u002Fmcp\u002Flimits-and-errors":3,"docs-navigation":476,"docs-surround-\u002Fdocs\u002Fmcp\u002Flimits-and-errors":558},{"id":4,"title":5,"body":6,"description":467,"extension":468,"icon":469,"meta":470,"navigation":471,"path":472,"seo":473,"stem":474,"__hash__":475},"docs\u002Fdocs\u002F2.mcp\u002F6.limits-and-errors.md","Limits and errors",{"type":7,"value":8,"toc":456},"minimark",[9,13,18,22,33,52,56,139,143,182,191,195,202,206,213,393,397,400,416,423,439,443],[10,11,5],"h1",{"id":12},"limits-and-errors",[14,15,17],"h2",{"id":16},"plan-driven-limits","Plan-driven limits",[19,20,21],"p",{},"Per-account limits are set by your subscription plan. Read them at runtime:",[23,24,25],"blockquote",{},[19,26,27,28,32],{},"Call ",[29,30,31],"code",{},"get_account"," and tell me my plan limits.",[19,34,35,36,39,40,43,44,47,48,51],{},"The response includes ",[29,37,38],{},"plan.limits"," (max sites, max domains, storage, bandwidth) and ",[29,41,42],{},"usage"," (current counts and bytes). Hitting a plan limit returns a clear error from ",[29,45,46],{},"create_site"," or a deploy tool - the agent should surface the limit and either free space (",[29,49,50],{},"delete_site",") or suggest an upgrade.",[14,53,55],{"id":54},"deploy-payload-limits","Deploy payload limits",[57,58,59,75],"table",{},[60,61,62],"thead",{},[63,64,65,69,72],"tr",{},[66,67,68],"th",{},"Constraint",[66,70,71],{},"Value",[66,73,74],{},"Why",[76,77,78,97,110,128],"tbody",{},[63,79,80,87,90],{},[81,82,83,86],"td",{},[29,84,85],{},"deploy_files"," total payload",[81,88,89],{},"≤ ~1 MB practical, hard cap ~6 MB",[81,91,92,93,96],{},"JSON-RPC + Lambda payload caps. For anything larger, use ",[29,94,95],{},"deploy_create_upload",".",[63,98,99,104,107],{},[81,100,101,103],{},[29,102,95],{}," part size",[81,105,106],{},"~5 MB per part",[81,108,109],{},"S3 multipart minimum. The server returns one presigned PUT URL per part.",[63,111,112,115,122],{},[81,113,114],{},"Presigned PUT URL TTL",[81,116,117,118,121],{},"A few hours (",[29,119,120],{},"expiresAt"," returned in the envelope)",[81,123,124,125,127],{},"Use the URLs promptly; if they expire, call ",[29,126,95],{}," again.",[63,129,130,133,136],{},[81,131,132],{},"Recommended bundling",[81,134,135],{},"Zip when > 3 files OR any file > ~1 MB",[81,137,138],{},"The fileWorker auto-extracts a single-zip upload, preserving subdirectories.",[14,140,142],{"id":141},"oauth-ttls","OAuth TTLs",[57,144,145,158],{},[60,146,147],{},[63,148,149,152,155],{},[66,150,151],{},"Token",[66,153,154],{},"Lifetime",[66,156,157],{},"Notes",[76,159,160,171],{},[63,161,162,165,168],{},[81,163,164],{},"Access token",[81,166,167],{},"1 hour",[81,169,170],{},"Refreshed silently by your MCP client.",[63,172,173,176,179],{},[81,174,175],{},"Refresh token",[81,177,178],{},"90 days",[81,180,181],{},"Rotates on each refresh; old refresh token is invalidated.",[19,183,184,185,190],{},"After 90 days of inactivity, the next tool call returns 401 and your client opens the consent flow again. See ",[186,187,189],"a",{"href":188},"\u002Fdocs\u002Fmcp\u002Fauthentication","Authentication"," for the full flow.",[14,192,194],{"id":193},"rate-limits","Rate limits",[19,196,197,198,201],{},"The Hostsmith API enforces per-account rate limits to protect partition capacity. The MCP server passes API responses through, so a rate-limit hit surfaces as a tool error with retry guidance. Treat any ",[29,199,200],{},"429","-style error as backoff-and-retry; do not loop without a delay.",[14,203,205],{"id":204},"error-categories","Error categories",[19,207,208,209,212],{},"MCP tools return errors as ",[29,210,211],{},"{ isError: true, content: [{ type: \"text\", text: \"\u003Cmessage>\" }] }",". The text is human-readable and intended for the agent to surface to the user.",[57,214,215,228],{},[60,216,217],{},[63,218,219,222,225],{},[66,220,221],{},"Category",[66,223,224],{},"Typical trigger",[66,226,227],{},"What the agent should do",[76,229,230,244,257,270,287,311,332,347,360,373],{},[63,231,232,238,241],{},[81,233,234],{},[235,236,237],"strong",{},"Auth (401)",[81,239,240],{},"Access token expired or revoked.",[81,242,243],{},"Reconnect the client; the next call re-auths.",[63,245,246,251,254],{},[81,247,248],{},[235,249,250],{},"Forbidden (403)",[81,252,253],{},"Token scopes don't cover the call (rare - the server requests the full set).",[81,255,256],{},"Reconnect to refresh scopes.",[63,258,259,264,267],{},[81,260,261],{},[235,262,263],{},"Validation (400)",[81,265,266],{},"Bad input - subdomain pattern, partition mismatch, missing required field.",[81,268,269],{},"Surface the message; do not retry the same call unchanged.",[63,271,272,277,280],{},[81,273,274],{},[235,275,276],{},"Conflict (409)",[81,278,279],{},"Subdomain already taken; site name in use.",[81,281,282,283,286],{},"Pick a different subdomain; for shared domains, omit ",[29,284,285],{},"subdomain"," to auto-generate.",[63,288,289,294,300],{},[81,290,291],{},[235,292,293],{},"Not found (404)",[81,295,296,299],{},[29,297,298],{},"siteId"," doesn't exist or is in another partition.",[81,301,302,303,306,307,310],{},"Re-resolve via ",[29,304,305],{},"list_sites","; pass ",[29,308,309],{},"partition"," explicitly if needed.",[63,312,313,318,326],{},[81,314,315],{},[235,316,317],{},"Plan limit",[81,319,320,322,323,96],{},[29,321,46],{}," would exceed ",[29,324,325],{},"plan.limits.maxSites",[81,327,328,329,331],{},"Surface the limit; ",[29,330,50],{}," to free space or suggest upgrade.",[63,333,334,339,344],{},[81,335,336],{},[235,337,338],{},"Domain not active",[81,340,341,343],{},[29,342,46],{}," called against a domain still validating or failed.",[81,345,346],{},"Surface state; do not retry - the user fixes it in the app.",[63,348,349,354,357],{},[81,350,351],{},[235,352,353],{},"Rate limit (429)",[81,355,356],{},"Too many requests in a short window.",[81,358,359],{},"Wait and retry once; if it recurs, surface to the user.",[63,361,362,367,370],{},[81,363,364],{},[235,365,366],{},"Server (5xx)",[81,368,369],{},"Transient backend issue.",[81,371,372],{},"Retry once after a short delay; otherwise surface.",[63,374,375,380,388],{},[81,376,377],{},[235,378,379],{},"Confirmation required",[81,381,382,384,385,96],{},[29,383,50],{}," called without ",[29,386,387],{},"confirm: true",[81,389,390,391,96],{},"Confirm with the user, then call again with ",[29,392,387],{},[14,394,396],{"id":395},"retry-guidance","Retry guidance",[19,398,399],{},"Safe to retry automatically (with a short delay):",[401,402,403,407,410],"ul",{},[404,405,406],"li",{},"5xx server errors.",[404,408,409],{},"429 rate-limit errors (back off, then retry once).",[404,411,412,413,415],{},"Transient network failures during a presigned S3 PUT (the URLs stay valid until ",[29,414,120],{},").",[19,417,418,419,422],{},"Do ",[235,420,421],{},"not"," retry without changes:",[401,424,425,428],{},[404,426,427],{},"4xx validation, conflict, or auth errors. Surface the message; the agent or user must change something.",[404,429,430,432,433,435,436,438],{},[29,431,95],{}," envelopes after ",[29,434,120],{}," - call ",[29,437,95],{}," again to get fresh URLs.",[14,440,442],{"id":441},"diagnosing-failed-deploys","Diagnosing failed deploys",[19,444,445,446,448,449,452,453,455],{},"If ",[29,447,85],{}," returns success but ",[29,450,451],{},"get_site"," shows a non-active status, the deploy was accepted but post-processing (zip extraction, content scan) is still running or failed. Wait a few seconds and call ",[29,454,451],{}," again. If it stays in a failed state, surface the status to the user and inspect the site in the app for details.",{"title":457,"searchDepth":458,"depth":458,"links":459},"",2,[460,461,462,463,464,465,466],{"id":16,"depth":458,"text":17},{"id":54,"depth":458,"text":55},{"id":141,"depth":458,"text":142},{"id":193,"depth":458,"text":194},{"id":204,"depth":458,"text":205},{"id":395,"depth":458,"text":396},{"id":441,"depth":458,"text":442},"Quotas, payload limits, OAuth TTLs, and how to interpret MCP tool errors.","md","solar:shield-warning-bold",{},null,"\u002Fdocs\u002Fmcp\u002Flimits-and-errors",{"title":5,"description":467},"docs\u002F2.mcp\u002F6.limits-and-errors","Buaf2F7HIaOOAev8zB9y5_adK1NW4hMHvnchrpBBmuU",[477],{"title":478,"path":479,"stem":480,"children":481,"page":557},"Docs","\u002Fdocs","docs",[482,509,539],{"title":483,"path":484,"stem":485,"children":486,"page":-1,"icon":488},"Getting Started","\u002Fdocs\u002Fgetting-started","docs\u002F1.getting-started\u002Findex",[487,489,493,497,501,505],{"title":483,"path":484,"stem":485,"icon":488},"solar:rocket-bold",{"title":490,"path":491,"stem":492},"Introduction","\u002Fdocs\u002Fgetting-started\u002Fintroduction","docs\u002F1.getting-started\u002F1.introduction",{"title":494,"path":495,"stem":496},"Quick Start","\u002Fdocs\u002Fgetting-started\u002Fquick-start","docs\u002F1.getting-started\u002F2.quick-start",{"title":498,"path":499,"stem":500},"Sites","\u002Fdocs\u002Fgetting-started\u002Fsites","docs\u002F1.getting-started\u002F3.sites",{"title":502,"path":503,"stem":504},"Custom Domains","\u002Fdocs\u002Fgetting-started\u002Fcustom-domains","docs\u002F1.getting-started\u002F4.custom-domains",{"title":506,"path":507,"stem":508},"Support","\u002Fdocs\u002Fgetting-started\u002Fsupport","docs\u002F1.getting-started\u002F5.support",{"title":510,"path":511,"stem":512,"children":513,"page":-1,"icon":515},"MCP","\u002Fdocs\u002Fmcp","docs\u002F2.mcp\u002Findex",[514,516,520,524,526,530,534,535],{"title":510,"path":511,"stem":512,"icon":515},"solar:plug-circle-bold",{"title":517,"path":518,"stem":519},"Quick start","\u002Fdocs\u002Fmcp\u002Fquick-start","docs\u002F2.mcp\u002F1.quick-start",{"title":521,"path":522,"stem":523},"Clients","\u002Fdocs\u002Fmcp\u002Fclients","docs\u002F2.mcp\u002F2.clients",{"title":189,"path":188,"stem":525},"docs\u002F2.mcp\u002F3.authentication",{"title":527,"path":528,"stem":529},"Tools","\u002Fdocs\u002Fmcp\u002Ftools","docs\u002F2.mcp\u002F4.tools",{"title":531,"path":532,"stem":533},"Recipes","\u002Fdocs\u002Fmcp\u002Frecipes","docs\u002F2.mcp\u002F5.recipes",{"title":5,"path":472,"stem":474},{"title":536,"path":537,"stem":538},"FAQ","\u002Fdocs\u002Fmcp\u002Ffaq","docs\u002F2.mcp\u002F7.faq",{"title":540,"path":541,"stem":542,"children":543,"page":-1,"icon":545},"Developers","\u002Fdocs\u002Fdevelopers","docs\u002F3.developers\u002Findex",[544,546,549,553],{"title":540,"path":541,"stem":542,"icon":545},"solar:code-bold",{"title":189,"path":547,"stem":548},"\u002Fdocs\u002Fdevelopers\u002Fauthentication","docs\u002F3.developers\u002F1.authentication",{"title":550,"path":551,"stem":552},"API Explorer","\u002Fdocs\u002Fdevelopers\u002Fapi-explorer","docs\u002F3.developers\u002F2.api-explorer",{"title":554,"path":555,"stem":556},"Node.js SDK","\u002Fdocs\u002Fdevelopers\u002Fsdk","docs\u002F3.developers\u002F3.sdk",false,[559,560],{"title":531,"path":532,"stem":533,"children":-1},{"title":536,"path":537,"stem":538,"children":-1},1778091982251]