---
topic: errors
---

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

# Errors and retries

**On this page:** Errors and retries (every call), Errors

> 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). |
| `missing_source_file` | 400 | No | No source field, or an empty files list. |
| `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. |
| `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. |
| `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. |
| `source_too_large / too_many_files` | 413 | No | Trim the upload (see large_apps) or use the .tar.gz upload. |
| `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. |
| `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. |
| `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. |

**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