Skip to content

Errors ​

The envelope ​

Every failure returns the same shape:

json
{
  "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 ​

StatusMeaningCommon causes
401Not authenticatedMissing token, expired token, or a token issued for a different audience
403Authenticated, not allowedMissing scope; or a workspace that belongs to another organization
404Not found in this workspaceUnknown id, slug or domain — including one that exists in a workspace you are not using
409Conflict with current stateSlug 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)
422Validation failedConfirmation field does not match; value outside the allowed set; goal or funnel that does not match the distribution's type
413Too largeA queue send whose message body or total size is over the limit (too_large)
429Rate limitedRepeated 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.

CodeStatusMeaning
NETWORK_RULE_INVALID400Not 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_WIDE400A range wider than /8 (IPv4) or /16 (IPv6)
NETWORK_RULE_LIMIT409Over a network rule limit
NETWORK_SELF_LOCKOUT409The 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.

See also ​