Misleading error on invalid job dependencies

Summary

When invalid job dependencies are specified in the YAML configuration we drop the job prior to running it and display the following message to the user:

The message indicates only one of many reasons why this job has invalid dependencies.

Steps to reproduce

rspec:
  needs:
    - project: org/another-project
      job: the-dependency
      ref: master
      artifacts: true

This can fail because of several reasons:

1. Cross project artifacts download feature is not available for the given project/plan
2. User doesn't have permissions to read the job in that project
3. Specific combination of project - job - ref was not found or job was not successful

rspec:
  needs:
    - pipeline: $UPSTREAM_PIPELINE_ID
      job: the-dependency
      artifacts: true

This new syntax being introduced for #255983 (closed) can fail if:

1. Pipeline was not found in the current pipeline's hierarchy (parent-child pipelines) - must be part of the same hierarchy excluding current pipeline
2. Specific combination of pipeline - job was not found or job was not successful

Example Project

What is the current bug behavior?

The message is misleading because it refers only to partial use cases.

What is the expected correct behavior?

A more exhaustive error message should be used. Either a message that can include all possible cases why this may fail or a specific error message according to the condition that fails first.

In any case we should link to the right documentation section as dependencies key is only one of many cases that we support to define dependencies (e.g. needs for local, cross-project and cross-pipeline artifacts download).

Proposal

If we can get the list of needed artifacts:

This job could not start because it could not retrieve the needed artifacts: 
<list of artifacts here>
Learn More.

If we cannot get the list of artifacts (see design below)

This job could not start because it could not retrieve the needed artifacts. 
Learn More.