> ## 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.

# Errors

> HTTP error codes, error response format, and how to handle each error type.

## Error response format

All errors return JSON with an `error` field:

```json theme={null}
{
  "error": "Human-readable description of the error"
}
```

Some errors include additional fields:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/rest-api/authentication) for setup.

```json theme={null}
{ "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.

```json theme={null}
{ "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.

```json theme={null}
{ "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.

```json theme={null}
{ "error": "A flow with this name already exists" }
```

***

### 429 Too Many Requests

Rate limit exceeded. See [rate limits](/rest-api/rate-limits).

```json theme={null}
{
  "error": "Rate limit exceeded",
  "retryAfter": 23
}
```

***

### 500 Internal Server Error

An unexpected error occurred on Zenstep's servers.

```json theme={null}
{ "error": "Internal server error" }
```

If you encounter persistent 500 errors, check the [Zenstep status page](https://status.getzenstep.com) and contact support if the issue persists.

***

## Handling errors in code

```javascript theme={null}
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();
}
```