Errors
The envelope
Every failure returns the same shape:
{
"error": {
"code": "forbidden",
"message": "workspace does not belong to organization"
}
}code is stable and safe to branch on. message is for people and may change.
Status codes
| Status | Meaning | Common causes |
|---|---|---|
| 401 | Not authenticated | Missing token, expired token, or a token issued for a different audience |
| 403 | Authenticated, not allowed | Missing scope; or a workspace that belongs to another organization |
| 404 | Not found in this workspace | Unknown id, slug or domain — including one that exists in a workspace you are not using |
| 409 | Conflict with current state | Slug already taken; attaching a domain that is not verified yet; signalling a workflow run that has finished (run_finished); a submitted file's download link used before its scan is clean (not_ready) |
| 422 | Validation failed | Confirmation field does not match; value outside the allowed set; goal or funnel that does not match the distribution's type |
| 413 | Too large | A queue send whose message body or total size is over the limit (too_large) |
| 429 | Rate limited | Repeated domain creation, an endpoint over its per-minute rate, a queue send that is too fast (rate_limited) or into a full queue (queue_full), a workflow start past the active-run cap (limit_reached), or an agent or token over its daily form-submission reads — see Limits |
The ones worth understanding
401 with a valid-looking token
Tokens are audience-specific. A token for the MCP server is not a token for https://api.edge.deca-dev.com. If the same credentials work through an agent but not over HTTP, check the audience before anything else.
403 ACCESS_DOWNGRADE
Making a distribution public, turning off require_mfa, or removing a sign-in method needs access.write. The message names the fields. The distribution is unchanged.
NETWORK_* codes
Network rule changes either apply in full or not at all.
| Code | Status | Meaning |
|---|---|---|
NETWORK_RULE_INVALID | 400 | Not an IP address, range, or ISO country code; a range with host bits set (the message suggests the right one); an unknown kind or applies_to |
NETWORK_RULE_TOO_WIDE | 400 | A range wider than /8 (IPv4) or /16 (IPv6) |
NETWORK_RULE_LIMIT | 409 | Over a network rule limit |
NETWORK_SELF_LOCKOUT | 409 | The new allow list would refuse caller_ip. Add that address too, or repeat with confirm |
403 when your other calls work
Two different causes produce this, and the message distinguishes them:
- A missing scope. The message names the scope. See Permission scopes.
- A workspace outside your organization. Edge will not let a token reach across organizations, including via
{org_id}in the path. That value must equal your token's organization.
404 for something you can see in the console
Distributions and related resources are scoped to a workspace. If you have more than one and the request resolved to your default workspace, a distribution in another workspace is genuinely not found from that request's point of view. Pass workspace_id as a query parameter or JSON field. GET /v1/logs/stream requires it explicitly.
409 on a domain attach
A domain must be verified before it can be attached. Verification fails silently from the caller's perspective when DNS has not propagated — the TXT record is simply not visible yet. Wait, verify again, then attach.
422 on a delete
Deleting a distribution or a domain requires repeating its identity in the request body — slug for a distribution, confirm_fqdn for a domain. A value that does not match is a 422 rather than a deletion.
422 on a file read
Only files whose scan finished clean can be read. A file still scanning, rejected or scan_failed is refused, and the message names its status. content is available for images and PDF up to 10 MiB, and text only when the file has extracted text; otherwise ask for a link.
Visitor-facing lanes
/_upload and /_submit answer the visitor's browser, not an API client, and use a flat body: {"error": "invalid_upload", "field": "resume", "reason": "type"}. Their codes are listed under Form uploads.
Deployment failures are not HTTP errors
A deployment that cannot be processed does not fail the request that created it. The request succeeds; the deployment's status later becomes failed.
So a 200 from commit means the work was accepted, not that it worked. Poll GET /v1/deployments/{id} until status is ready or failed.
The most common cause is a bundle that is not a gzipped tar, or one whose index.html is nested inside a folder instead of sitting at the archive root.