> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Validation errors and recovery strategies

The MCP tools provide detailed error messages designed to help AI agents understand and correct issues.

## Project Context Errors

### NO\_PROJECT\_CONTEXT

Returned when no project context is set and no `projectId` parameter is provided.

```json theme={null}
{
  "error": {
    "code": "NO_PROJECT_CONTEXT",
    "message": "No project context set. Use set_project to set a default project or provide projectId parameter.",
    "hint": "The project_context prompt provides available projects and guidance."
  }
}
```

**Recovery**: Call `set_project` with a valid project ID, or include `projectId` in the tool call.

### PROJECT\_ACCESS\_DENIED

Returned when the user doesn't have access to the specified project.

```json theme={null}
{
  "error": {
    "code": "PROJECT_ACCESS_DENIED",
    "message": "You do not have access to project proj_999",
    "hint": "Use list_projects to see available projects."
  }
}
```

**Recovery**: Use `list_projects` to find projects you have access to.

## Content Validation Errors

The `create_content` and `update_content` tools validate all content against the content type's JSON schema.

### VALIDATION\_ERROR

General validation failure with detailed error information.

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Content validation failed against content type schema",
    "details": {
      "contentTypeId": "ct_story_001",
      "contentTypeVersion": 2,
      "validationErrors": [
        {
          "path": "/components/0/text",
          "schemaPath": "#/definitions/StoryParagraph/properties/text",
          "keyword": "maxLength",
          "message": "Text must not exceed 10000 characters",
          "params": {
            "limit": 10000,
            "actual": 10523
          },
          "suggestion": "Reduce text length by 523 characters or split into multiple paragraphs"
        }
      ]
    }
  }
}
```

### SCHEMA\_STRUCTURE\_ERROR

Using components or fields not allowed by the content type.

```json theme={null}
{
  "error": {
    "code": "SCHEMA_STRUCTURE_ERROR",
    "message": "Content structure does not match content type schema",
    "details": {
      "validationErrors": [
        {
          "path": "/components/2",
          "message": "Invalid component type 'StoryVideo' - not in allowed components list",
          "allowedTypes": ["StoryParagraph", "StoryPhoto", "StoryPhotoGallery", "StorySubheader"],
          "suggestion": "Use one of the allowed component types for this content type"
        }
      ]
    }
  }
}
```

**Recovery**: Check the content type schema for allowed component types.

### REQUIRED\_FIELD\_ERROR

Missing mandatory fields.

```json theme={null}
{
  "error": {
    "code": "REQUIRED_FIELD_ERROR",
    "message": "Required fields are missing",
    "details": {
      "validationErrors": [
        {
          "path": "/title",
          "message": "Required field 'title' is missing",
          "suggestion": "Add a 'title' field with a string value (1-200 characters)"
        },
        {
          "path": "/components",
          "message": "Required field 'components' is missing",
          "suggestion": "Add a 'components' array with at least one component"
        }
      ]
    }
  }
}
```

**Recovery**: Add all required fields as specified in the schema.

### TYPE\_MISMATCH\_ERROR

Incorrect data types.

```json theme={null}
{
  "error": {
    "code": "TYPE_MISMATCH_ERROR",
    "message": "Field types do not match schema requirements",
    "details": {
      "validationErrors": [
        {
          "path": "/components/0/asset/id",
          "message": "Expected string, got number",
          "expected": "string",
          "actual": "number",
          "value": 12345,
          "suggestion": "Provide asset ID as a string, e.g., \"asset-12345\""
        }
      ]
    }
  }
}
```

**Recovery**: Convert the value to the expected type.

### CONSTRAINT\_VIOLATION

Exceeding limits or breaking rules.

```json theme={null}
{
  "error": {
    "code": "CONSTRAINT_VIOLATION",
    "message": "Content violates schema constraints",
    "details": {
      "validationErrors": [
        {
          "path": "/subtitle",
          "keyword": "maxLength",
          "message": "Subtitle exceeds maximum length of 100 characters",
          "params": {
            "limit": 100,
            "actual": 125
          },
          "suggestion": "Shorten subtitle to 100 characters or less"
        }
      ]
    }
  }
}
```

**Recovery**: Adjust the value to meet the constraint.

### ASSET\_NOT\_FOUND

Referencing non-existent assets.

```json theme={null}
{
  "error": {
    "code": "ASSET_NOT_FOUND",
    "message": "Referenced assets do not exist",
    "details": {
      "validationErrors": [
        {
          "path": "/asset/id",
          "message": "Asset 'asset-999' not found in project",
          "assetId": "asset-999",
          "suggestion": "Use search_assets to find a valid asset ID. Assets must be uploaded through the CMS interface before use."
        }
      ]
    }
  }
}
```

**Recovery**: Use `search_assets` to find valid asset IDs.

### MULTIPLE\_VALIDATION\_ERRORS

Multiple errors grouped and summarized.

```json theme={null}
{
  "error": {
    "code": "MULTIPLE_VALIDATION_ERRORS",
    "message": "Multiple validation errors found",
    "summary": {
      "total": 5,
      "byCategory": {
        "missingRequired": 2,
        "invalidType": 1,
        "constraintViolation": 2
      }
    },
    "details": {
      "validationErrors": [
        { "..." : "..." }
      ]
    }
  }
}
```

## Recovery Strategies

When encountering validation errors:

1. **Parse the suggestion field**: Every error includes actionable guidance
2. **Review the schema**: Use `get_content_type` to understand requirements
3. **Fix asset issues**: Use `search_assets` to find valid asset IDs
4. **Handle length constraints**: Split long content into multiple components
5. **Check component types**: Ensure using only allowed component types

## Error Prevention Best Practices

<Steps>
  <Step title="Fetch the schema first">
    Always use `get_content_type` before creating content to understand the structure and constraints.
  </Step>

  <Step title="Validate asset IDs">
    Use `search_assets` to verify assets exist before referencing them.
  </Step>

  <Step title="Check length limits">
    Review `maxLength` constraints in the schema for all text fields.
  </Step>

  <Step title="Use correct component types">
    Match component type names exactly as defined in the schema's `definitions`.
  </Step>

  <Step title="Include all required fields">
    Check the schema's `required` arrays at each level of the structure.
  </Step>
</Steps>