---
topic: errors
---

[← Guide home](https://embarko.ai/docs)

# Errors and retries

**On this page:** Errors and retries (every call), Errors, What to tell the person

> Plain words unless the person is a developer. Never invent a link, name or code. [Rules](https://embarko.ai/docs/prerequisites)

Every reply that fails has a code. Find it below, do what it says, and retry only as the rules allow.

**Errors and retries (every call)**

- 400, 401, 403, 404, 409, 422: retry No. The request is wrong. Fix what `code` names, then send a different request.
- 500, 502, 503, 504: retry Once. Wait 2 seconds and retry once. For a deploy, check status first: it may have been accepted. Where a specific code below says otherwise (app_name_check_failed), that row wins.
- 429, or a code that says wait: retry Later. Wait retryAfterMs if the reply gives it, otherwise a few minutes, then retry once.
- Timeout / no reply on a deploy: retry Check first. Call status before retrying, or you may deploy twice.

Backoff: A code's own row always beats these general rules. Sending a corrected request (new name, new folder, fixed code) is a new request, not a retry. Never more than one retry, never in a loop. If the retry fails too, stop and tell the person, and report it if it looks like Embarko's fault.

**Errors**

| Code | Status | Retry | What to do |
| --- | --- | --- | --- |
| `invalid_app_name` | 400 | No | Name missing or breaks the pattern. Slugify and resend. |
| `app_name_too_short / app_name_too_long` | 400 | No | 3-63 characters. |
| `invalid_app_version / invalid_app_type / invalid_agent_name` | 400 | No | Fix or drop that header (printable ASCII, 60 characters max). |
| `invalid_app_id` | 400 | No | X-App-Id must be app.id from an earlier deploy reply, exactly as given. Fix it or leave the header out. |
| `missing_source_file` | 400 | No | No source field, or an empty files list. |
| `upload_not_found` | 404 | No | Upload sessions: the upload expired (60 minutes unused), was already deployed, or was opened with a different token. Open a new one and send the files again. |
| `upload_app_mismatch / files_and_upload_id / invalid_file_append` | 409 / 400 | No | Upload sessions: deploy under the appName the upload was opened with; send uploadId without files; append must be true or false. |
| `too_many_uploads` | 429 | Later | 5 uploads are already open for this token. Deploy one, or wait for unused ones to expire. |
| `invalid_file_path / invalid_file_content / invalid_file_encoding / invalid_json` | 400 | No | JSON upload only: relative paths, string content, encoding utf8 or base64. |
| `unauthorized` | 401 | No | The token is invalid or revoked. Leaving the header out is an anonymous deploy, not an error; an empty or made-up token is a 401. |
| `app_not_found` | 404 | No | No app this token can reach has that appId (X-App-Id or embarko.json). Check you are using the right token. If the app should be new, remove "appId" from embarko.json and deploy. |
| `no_access` | 403 | No | The person the token belongs to can't do this in the workspace named in the message: they are no longer in it. Nothing was deployed. Ask them to get access there, or for a token from that workspace. Never deploy under a new name to get round it. |
| `app_deleted` | 410 | No | The app with that appId was deleted. Ask the person before deploying it again. If they want it back as a new app, remove "appId" from embarko.json and deploy. |
| `app_id_mismatch` | 409 | No | The appId (X-App-Id or embarko.json) belongs to another app, and the app name you sent was never that app's name. Usually the code was copied from that app. For a new app, remove "appId" from embarko.json and deploy. To update the other app, deploy under its name. |
| `host_not_allowed (from your own sandbox)` | 403 | No | Not Embarko: your environment blocks ship.embarko.ai. Switch route: connector, or ask the person to connect it. A big app goes through the connector in parts (see large_apps on the deploy topic; it also says how they can allow ship.embarko.ai for your sandbox, if they choose). |
| `permission_denied` | 403 | No | The token's owner may not publish this app (that needs Full access to it, permission "app.deploy") or add new apps ("app.create"). The reply names their access. Nothing was deployed. Tell the person (say_to_user.no_permission). |
| `app_name_taken` | 409 | No | Another account owns the name. On a first deploy, pick a close variant yourself: add the person's or business name if you know it, otherwise a short word (portfolio → portfolio-site, then portfolio-app). Mention the name with the link. Ask only if the exact name matters to them. |
| `app_name_reserved` | 409 | No | A platform name. Pick a different one (see name_rules.reserved). |
| `rename_in_progress` | 409 | Later | The app's address is being changed. Wait, then deploy under the new name. |
| `app_moved` | 409 | No | The app was moved to another workspace this token can't reach. Nothing was deployed. Do not deploy it under a new name: that makes a second copy. Ask the person for a personal key (see claim), or for access to the workspace it moved to. |
| `source_too_large / too_many_files` | 413 | No | Over 25MB or 2,000 files: trim it (see large_apps), or use the .tar.gz upload. No way to send that from the chat: give the person the file for the upload page (say_to_user.too_big_for_chat). |
| `no_manifest_at_root` | 422 | No | Read foundNestedAt and package from that folder. |
| `app_nested_in_subdirectory` | 422 | No | Deploy the folder named in deployThisInstead. |
| `unsupported_storage_pattern` | 422 | No | The app uses window.storage. Switch to SQLite under DATA_DIR. |
| `invalid_embarko_json` | 400 | No | embarko.json is not valid JSON (the message gives the line and column), not one object, has "schedules" that is not a list, or is over 64 KB. Fix the file and deploy again (see embarko-json). |
| `secrets_in_embarko_json` | 400 | No | embarko.json looks like it holds a secret. Remove it and set it as an env var instead (see env-vars). |
| `invalid_schedules / invalid_cron / schedule_too_frequent / invalid_timezone / invalid_path / duplicate_schedule_path / schedule_limit_reached` | 400 | No | A schedule in embarko.json is wrong; the message names the entry, e.g. "Schedule 1: ...". Fix it and deploy again (see schedules). |
| `in_process_timer (warning, deploy goes ahead)` | 202 | No | The app uses a timer library (node-cron, APScheduler...). Those jobs are not guaranteed to run on Embarko and can stop with no error. Move each job into a route, list it under "schedules" in embarko.json (see schedules), then deploy again. |
| `app_renamed (notice, deploy goes ahead)` | 202 | No | The app was renamed in the dashboard since you last deployed. This deploy reached it under its current name (app.name). Use that name from now on and tell the person the new link. |
| `app_moved (notice, deploy goes ahead)` | 202 | No | The app was moved to another workspace since you last deployed, and this deploy updated it there. Same link, same appId: change nothing. Tell the person in one line, using notices[].detail. |
| `embarko_json_not_at_top / embarko_json_misnamed / embarko_json_unknown_keys / schedules_unchanged / schedules_on_static_site (warnings, deploy goes ahead)` | 202 | No | Read warnings[].detail and do what it says: move or rename the file, drop keys Embarko ignores, or use [] to remove schedules (see embarko-json). |
| `app_kind_changed` | 422 | No | A static site cannot become a server app. Use a new name. |
| `(rate limited)` | 429 | Later | Wait retryAfterMs, or a few minutes, then retry once. |
| `builds_paused` | 503 | Later | Embarko is briefly short of capacity and nothing was accepted. Wait retryAfterSeconds (10 minutes), then send the identical request once. Tell the person deploys are paused for a few minutes, not broken. |
| `deploy_failed / publish_failed` | 500 | Once | Check status first, then redeploy once. If it repeats, report it. |
| `app_name_check_failed` | 502 | Once | Transient, and nothing was accepted: wait 2 seconds and send the identical request once. No status check needed. |
| `(other 5xx)` | 502/503/504 | Once | Check status before re-sending: it may have been accepted. |

**What to tell the person**

- no_permission: "Your access ({your access to the app, or your role}) doesn't let me {what it was}. An Owner or Admin can give you more on Members: https://embarko.ai/app/people"

**Next:** Find the code, fix the request or the app, then send a different request.

**Related:** [deploy](https://embarko.ai/docs/deploy) · [logs](https://embarko.ai/docs/logs) · [feedback](https://embarko.ai/docs/feedback)

---

[Guide home](https://embarko.ai/docs) · JSON: add .json