Good results usually come from a clear first request and a quick look at one page before the rest. Start with the tips below, then check your allowances and the answers for when something stops.
When something stops
Read the error code first. REST errors return application/problem+json with a code, detail and requestId. With MCP, ask your agent to prepare a support report with the relevant calls, outcomes and available request or trace IDs. Review the report, then paste it into support chat or email it to hello@appscreens.com. Keep API keys, signed links and credential files private.
Tips for better results
- Share the project link. Paste the link to your AppScreens project so your agent works on the right one. For a new set, say so and name the app it is for.
- Bring your captures and a reference. Point your agent at your screenshots folder, or attach the images. Name an app whose style you like.
- Say your stores, devices and languages up front. For example: “iPhone and Android, in English and German.” Changing them halfway means redoing pages.
- Review one page first. Ask for one page at one size before the rest: “Show me page 1 on iPhone before you build the other pages.”
- Keep going in the same chat. Follow-ups such as “Make the headline shorter” or “Add French” apply to the same project.
- Make big changes in steps. Change the layout first, then the captions, then the translations, and check a preview after each step.
- Preview before you export or upload. Ask to see the screenshots or the store listing preview first. Nothing is sent to a store until you approve the destination.
- Start a new chat with a handover. When a chat gets long or new tools are missing, start a new one. Give it the project link, the agreed pages, sizes and languages, what still needs review and any export still running.
Getting a generic result or lots of questions? Build a fuller prompt here.
Check your allowance before big jobs
Each plan includes a weekly and monthly allowance of API requests and rendered images, plus a limit on renders running at once. All API keys and MCP connections on an account share them, so check what is left before a large render.
One rendered image is one page, in one language, on one device. Previews and exports both count, and only images that render successfully are charged.
Allowances by plan
Each week allows half the month, so a busy week can't use it all. Check what is left in Account > MCP Access or with get_account_usage.
| Allowance | Free | Pro | Scale |
|---|---|---|---|
| API requests per week / month | 500 / 1,000 | 15,000 / 30,000 | 30,000 / 60,000 |
| Rendered images per week / month | 25 / 50 | 1,500 / 3,000 | 3,000 / 6,000 |
| Renders at once | 1 | 2 | 3 |
- Waiting is free: wait_for_operation, get_operation, get_deployment, get_account_usage and MCP setup messages such as tools/list do not count as requests. Wait for pollAfterSeconds between progress checks; starting another render is not a progress check.
- Usage resets in UTC: Monday for the week, the 1st for the month. GET /v1/usage returns what is used, held by running renders and left. Read the live response rather than building plan numbers into a client.
- After a limit (429), the error names the allowance and when it resets; wait for Retry-After. RENDER_CONCURRENCY_LIMIT clears when a running render finishes.
- PLAN_REQUIRED and LANGUAGE_LIMIT_EXCEEDED mean the plan does not cover the request, so retrying will not help. Free accounts can preview designs that use Free features; Pro features and full-resolution exports need a paid plan.
- Saved projects have a separate limit (PROJECT_LIMIT_REACHED), and archived projects still count. The account owner decides whether to remove projects or change plan; an agent should never delete, archive or upgrade on its own.
Common errors
Sign-in failed (401)
For MCP, reconnect the client and sign in to AppScreens again. For REST, check that the API key is active, has not expired and is sent as Authorization: Bearer. Never paste a key or token into chat.
Missing access
Reconnect and approve the access the task needs, or create an API key with All access or Projects only. Read only cannot create, change or export projects.
Cannot connect
Check that the URL ends in /mcp (or /v1 for REST), and check your network and proxy settings. AppScreens uses Streamable HTTP, not the older SSE transport.
New tools or options missing
Your AI client keeps the AppScreens tool list from when it connected. Start a new chat, or reconnect AppScreens in the client’s connector or MCP settings (in Claude Code, run /mcp and reconnect), to load the current tools. Calls your client already knows keep working in the meantime.
My agent can’t see my screenshots
Coding clients read captures from the workspace you opened; chat clients need them attached. Ask your agent to list the files it found before it builds. If it still can’t find them, attach the images to the chat.
The text doesn’t fit
Ask for a shorter caption, then preview the longest language at the smallest size. Keep Match text size on so captions stay the same size across pages.
It changed my app’s interface
AppScreens places your captures exactly as they are. If a screen looks redrawn, it was added as artwork. Ask your agent to use your real capture in the device frame instead.
It’s working on the wrong project
Paste the project link from the editor and ask your agent to confirm the project name before it changes anything. If it already changed the wrong project, restore the earlier version from version history.
404 Not Found
Check the ID came from an earlier response and that you are signed in to the right account. Do not guess IDs.
409 Conflict
Someone or something changed the project, or a page cursor expired. Read the project again and decide what to keep. Restart paginated reads from the first page with the same filters.
A request timed out
Check list_operations, or read the project, before trying again. A repeated preview or export of the same version reuses the one still running.
The project is open in the editor
That is fine: agent changes appear in the open editor. If the editor has unsaved changes, it warns before saving over them. Never discard unsaved work in the browser.
PREVIEW_EXPIRED
Render a new preview. Expired links cannot be reused.
A store update was partial or uncertain
Read the store listing again and check each language before another approved preview. Restoring a project version does not undo store changes.
