Errors & Status Codes

All errors follow a consistent JSON envelope with an error machine-readable code and a message for humans. HTTP status codes follow REST conventions.

Error envelope

All error responses return { "error": "error_code", "message": "Description." }. The error field is a stable snake_case string you can match programmatically; message is for logging and display.

4xx — Client errors

400 invalid_input — Validation failed (missing or malformed field). 401 missing_token / invalid_token / expired_token — Authentication failed. 403 insufficient_scope / forbidden_ip / team_mismatch — Authorization failed. 404 not_found — Resource does not exist or belongs to another team. 409 conflict — Slug already taken, or trying to delete an active deployment.

4xx — Limit errors

403 limit_reached — Team has hit the maximum number of sites (5 on free plan). 422 — Deployment ZIP exceeds 500 MB unzipped, or contains more than 1 000 files.

5xx — Server errors

500 — Unexpected server or storage error. Retrying with exponential backoff is safe for idempotent requests (GET, DELETE). For upload POSTs, check if the deployment was created before retrying.

Code examples

cURL

# A 404 response looks like:
# HTTP/2 404
# { "error": "not_found", "message": "Site not found" }

curl -i "https://www.zyberspace.com/api/v1/{teamSlug}/sites/non-existent-site" \
  -H "Authorization: Bearer zxk_live_YOUR_API_KEY"

JavaScript

const res = await fetch(`https://www.zyberspace.com/api/v1/{teamSlug}/sites/my-site`, {
  headers: { Authorization: "Bearer zxk_live_YOUR_API_KEY" },
});

if (!res.ok) {
  const { error, message } = await res.json();
  console.error(`[${error}] ${message}`);
  // e.g. [not_found] Site not found
}

Base URL: https://www.zyberspace.com

Get your API key →