Error Handling

MCP workflow tools return structured error metadata that helps agents understand what went wrong and how to recover. This is the _agent field in error responses.

Resource Error Format (read-only resources)

When reading rad-tv:// resources via resources/read, errors are returned in the resource body as JSON:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Error Response Format

When a workflow tool fails, the response includes:

{
  "error": {
    "code": "CONTENT_NOT_FOUND",
    "message": "No content found with the given ID",
    "_agent": {
      "suggested_action": "Verify the content ID exists by calling get_me or channel_dashboard",
      "related_tools": ["get_me", "channel_dashboard", "create_content"],
      "common_cause": "Content was deleted or the DID is malformed",
      "retry": false
    }
  }
}

Error Codes

Code	Description	Retry?
`MISSING_INPUT`	Required argument not provided	No — fix input and retry
`CHANNEL_NOT_FOUND`	No channel found for the user or provided DID	No
`CONTENT_NOT_FOUND`	Content ID doesn't exist or isn't accessible	No
`ASSET_NOT_FOUND`	No uploaded asset found on the content	No
`NO_TRANSCODE_JOB`	Content has no transcode job to check	No
`INGESTION_TIMEOUT`	File upload didn't complete within the expected time	Yes
`ALL_ITEMS_FAILED`	All items in a batch operation failed	No — check individual results

The `_agent` Field

Every workflow error includes _agent metadata designed for agent self-correction:

Field	Type	Description
`suggested_action`	string	What the agent should do next
`related_tools`	[string]	Tools that might help resolve the issue
`common_cause`	string	Why this error typically occurs
`retry`	boolean	Whether retrying the same call might succeed

Examples

Missing Channel

{
  "error": {
    "code": "CHANNEL_NOT_FOUND",
    "message": "User has no channel",
    "_agent": {
      "suggested_action": "The user needs to create a channel on rad.live before using content tools",
      "related_tools": ["verify_connection"],
      "common_cause": "New user account without a channel",
      "retry": false
    }
  }
}

Upload Timeout

{
  "error": {
    "code": "INGESTION_TIMEOUT",
    "message": "File upload did not complete within 60 seconds",
    "_agent": {
      "suggested_action": "Retry with a longer timeout or check network connectivity",
      "related_tools": ["publish_video", "finalize_content_upload"],
      "common_cause": "Large file or slow network — upload is still in progress",
      "retry": true
    }
  }
}

Batch Import Failures

{
  "error": {
    "code": "ALL_ITEMS_FAILED",
    "message": "All 5 YouTube imports failed",
    "_agent": {
      "suggested_action": "Check individual results for error details. Common issues: disconnected YouTube account or private videos",
      "related_tools": ["list_youtube_videos", "import_youtube_and_publish"],
      "common_cause": "YouTube connection expired or videos are not accessible",
      "retry": false
    }
  }
}

Agent Recovery Pattern

When an agent encounters an error, it should:

Read the _agent.suggested_action — follow the specific guidance
Check _agent.retry — if true, retry the same call (possibly with different parameters)
Use _agent.related_tools — call these tools to gather more context before retrying
Report _agent.common_cause — explain to the user what likely went wrong

Non-workflow tools (like get_me, list_channels) use standard MCP error responses without the _agent field. The structured metadata is only available on compound workflow tools.

GraphQL Error Format

For reference, GraphQL errors follow the spec format and include structured extensions:

{
  "data": null,
  "errors": [
    {
      "message": "Field 'channel' requires subfield selection",
      "path": ["me"],
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED",
        "errorType": "ValidationError",
        "field": "channel",
        "suggestedFix": "Add subfields like: channel { id }",
        "documentation": "https://developers.rad.live/docs/errors/graphql_validation_failed"
      }
    }
  ]
}

REST endpoints return:

{
  "errors": [
    {
      "message": "Invalid token",
      "code": "UNAUTHENTICATED",
      "documentation": "https://developers.rad.live/docs/errors/unauthenticated"
    }
  ]
}

You can browse the full API error code reference at API Error Codes.

Error Handling

On this page