Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getzenstep.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Error response format

All errors return JSON with an error field: 
{
  "error": "Human-readable description of the error"
}
Some errors include additional fields: 
{
  "error": "Validation failed",
  "details": [
    { "path": "events[0].eventType", "message": "Invalid enum value" }
  ]
}

​
HTTP status codes

​
400 Bad Request

The request body failed validation. Check the details field for the specific validation errors. 
{
  "error": "Validation failed",
  "details": [
    { "path": "events", "message": "Array must contain at least 1 element(s)" }
  ]
}
Common causes:
  • Missing required fields
  • Invalid UUID format in path parameters
  • Event batch exceeds 50 items
  • eventType not one of: view, complete, dismiss, skip, custom

​
401 Unauthorized

Authentication failed. See authentication for setup. 
{ "error": "Unauthorized" }
Common causes:
  • Missing Authorization header
  • Incorrect snippet key
  • Expired session token (for dashboard-authenticated routes)

​
403 Forbidden

The authenticated credential does not have permission to access this resource. 
{ "error": "Forbidden" }
Common causes:
  • Accessing a resource belonging to a different organisation
  • Attempting to use a snippet-key-authenticated request on a session-only endpoint

​
404 Not Found

The requested resource does not exist, or does not belong to your organisation. 
{ "error": "Not found" }
Note: Zenstep returns 404 (not 403) when a resource exists but belongs to a different organisation. This prevents enumeration attacks.

​
409 Conflict

A uniqueness constraint was violated. 
{ "error": "A flow with this name already exists" }

​
429 Too Many Requests

Rate limit exceeded. See rate limits. 
{
  "error": "Rate limit exceeded",
  "retryAfter": 23
}

​
500 Internal Server Error

An unexpected error occurred on Zenstep’s servers. 
{ "error": "Internal server error" }
If you encounter persistent 500 errors, check the Zenstep status page and contact support if the issue persists.

​
Handling errors in code

async function callZenstepAPI(url, options) {
  const response = await fetch(url, options);

  if (!response.ok) {
    const body = await response
      .json()
      .catch(() => ({ error: "Unknown error" }));

    switch (response.status) {
      case 400:
        console.error("[Zenstep] Validation error:", body.details);
        break;
      case 401:
        console.error(
          "[Zenstep] Authentication failed — check your snippet key",
        );
        break;
      case 429:
        console.warn(
          `[Zenstep] Rate limited — retry after ${body.retryAfter}s`,
        );
        break;
      case 500:
        console.error("[Zenstep] Server error — check status.getzenstep.com");
        break;
      default:
        console.error("[Zenstep] API error:", body.error);
    }

    throw new Error(body.error);
  }

  return response.json();
}