API Error Codes

This section is the canonical reference for API error documentation links generated by api.rad.live.

When the API includes documentation in an error payload, it points to:

https://developers.rad.live/docs/errors/<error_code_slug>

Where <error_code_slug> is the lowercase enum code from the API (for example, GRAPHQL_VALIDATION_FAILED -> graphql_validation_failed).

Error response shape

GraphQL responses include machine-readable metadata in errors[].extensions:

{
  "errors": [
    {
      "message": "Field 'channel' requires subfield selection",
      "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 responses use:

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

Available codes

HTTP and GraphQL errors

FIELD_REQUIRED

A required field was not supplied.

Source: HTTP and GraphQL

HTTP status: 400

GRAPHQL_VALIDATION_FAILED

The GraphQL document does not match the published schema.

Source: HTTP and GraphQL

HTTP status: 400

INTERNAL_SERVER_ERROR

The server encountered an unexpected error.

Source: HTTP and GraphQL

HTTP status: 500

INVALID_INPUT

One or more supplied values are invalid.

Source: HTTP and GraphQL

HTTP status: 400

RATE_LIMIT_EXCEEDED

The caller exceeded the allowed request rate.

Source: HTTP and GraphQL

HTTP status: 429

RESOURCE_ALREADY_EXISTS

The requested resource conflicts with an existing resource.

Source: HTTP and GraphQL

HTTP status: 409

RESOURCE_NOT_FOUND

The requested resource does not exist or is not visible to the caller.

Source: HTTP and GraphQL

HTTP status: 404

SERVICE_UNAVAILABLE

A required service is temporarily unavailable.

Source: HTTP and GraphQL

HTTP status: 503

TOKEN_EXPIRED

The authentication token has expired and must be refreshed.

Source: HTTP and GraphQL

HTTP status: 401

TRANSCODE_FAILED

The media transcoding operation failed.

Source: HTTP and GraphQL

HTTP status: 422

UNAUTHENTICATED

Authentication credentials are missing or invalid.

Source: HTTP and GraphQL

HTTP status: 401

UNAUTHORIZED

The authenticated identity cannot perform this operation.

Source: HTTP and GraphQL

HTTP status: 403

UPLOAD_FAILED

The media upload operation failed.

Source: HTTP and GraphQL

HTTP status: 422

Workflow errors

ALL_ITEMS_FAILED

Every item in a batch workflow failed.

Source: Workflow

ASSET_NOT_FOUND

The workflow could not find the required uploaded media asset.

Source: Workflow

AUTO_FINALIZE_PENDING

The uploaded media is still being finalized by the server.

Source: Workflow

CHANNEL_NOT_FOUND

The authenticated user does not have the required channel.

Source: Workflow

CONTENT_NOT_FOUND

The requested content item could not be found.

Source: Workflow

IDEMPOTENCY_CLAIM_LOST

Another worker changed the durable workflow operation first.

Source: Workflow

IDEMPOTENCY_KEY_REUSED

The idempotency key was previously used with different input.

Source: Workflow

IDEMPOTENT_OPERATION_IN_PROGRESS

The matching durable workflow operation is still running.

Source: Workflow

INGESTION_TIMEOUT

The uploaded source did not become available before polling timed out.

Source: Workflow

INVALID_IDEMPOTENCY_KEY

The idempotency key is missing or does not match the supported format.

Source: Workflow

INVALID_OPERATION_ID

The durable workflow operation ID is malformed.

Source: Workflow

MISSING_INPUT

A workflow is missing an input required to choose its next step.

Source: Workflow

MULTIPLE_VIDEO_SOURCES

The workflow found multiple video sources and could not choose one safely.

Source: Workflow

NO_TRANSCODE_JOB

The content item does not have a transcoding job.

Source: Workflow

OPERATION_NOT_FOUND

No durable workflow operation is visible to the authenticated creator.

Source: Workflow

PUBLISH_FAILED

Processing completed but the content could not be published.

Source: Workflow

PUBLISH_NOT_PERSISTED

The publication request completed but public state was not confirmed on read-back.

Source: Workflow

PUBLISH_WORKFLOW_FAILED

The publishing workflow stopped after creating its content item.

Source: Workflow

YOUTUBE_IMPORT_FAILED

The YouTube workflow stopped after creating its content reference.

Source: Workflow

YOUTUBE_SYNC_DISCONNECTED

The creator must reconnect YouTube before synchronization can continue.

Source: Workflow

YOUTUBE_SYNC_INPUT_MISMATCH

A resumed YouTube catalog synchronization changed an immutable option.

Source: Workflow

YOUTUBE_SYNC_NOT_FOUND

The requested YouTube catalog synchronization does not exist for this creator.

Source: Workflow

YOUTUBE_SYNC_UPSTREAM

YouTube listing failed and the synchronization can resume from its saved page.

Source: Workflow