@@ -62,7 +62,8 @@ def resolve_attachment_secret(
                 e.response_code, e.error_message
             )
         except requests.RequestException:
-            error_code = CredentialErrorCode.CREDENTIAL_ACCESS_DENIED
+            # Connection error or timeout: the platform never answered.
+            error_code = CredentialErrorCode.CREDENTIAL_RESOLUTION_UNAVAILABLE
         else:
             if not isinstance(result, dict):
                 error_code = CredentialErrorCode.CREDENTIAL_ACCESS_DENIED
 
@@ -1,6 +1,7 @@
 from .attachment import (
     CredentialAttachment,
     get_credential_attachment,
+    resolve_credential_attachment,
     resolve_inject_credential,
 )
 from .errors import (
@@ -9,6 +10,8 @@
     InvalidResolvedSecretError,
     UnsupportedSecretTypeError,
     credential_error_code_from_http,
+    credential_error_guidance,
+    credential_error_summary,
 )
 from .materializer import CredentialCleanupError, MaterializedCredential, materialize
 from .resolved import (
@@ -57,10 +60,13 @@ def build_single_referenced_credential_element(provider_name: str):
     "UnsupportedSecretTypeError",
     "UsernamePasswordSecret",
     "credential_error_code_from_http",
+    "credential_error_guidance",
+    "credential_error_summary",
     "build_single_referenced_credential_element",
     "ensure_compatible",
     "get_credential_attachment",
     "materialize",
     "parse_resolved_secret",
+    "resolve_credential_attachment",
     "resolve_inject_credential",
 ]
@@ -8,7 +8,9 @@
 ``attachments`` is ``null`` when the inject has no reference: the injector then
 keeps its legacy credential fields and no resolution request is sent.
 
-``resolve_inject_credential`` is the single entry point injectors call.
+``resolve_inject_credential`` is the single entry point injectors call. An
+injector that reads the attachment while validating its input and resolves it
+later calls ``get_credential_attachment`` then ``resolve_credential_attachment``.
 """
 
 from dataclasses import dataclass, field
@@ -100,6 +102,23 @@ def resolve_inject_credential(
     attachment = get_credential_attachment(data)
     if attachment is None:
         return None
+    return resolve_credential_attachment(api, inject_id, attachment, expected_type)
+
+
+def resolve_credential_attachment(
+    api: "OpenAEV",
+    inject_id: str,
+    attachment: CredentialAttachment,
+    expected_type: Union[CredentialType, str],
+) -> ResolvedSecret:
+    """Resolve an attachment already read with ``get_credential_attachment``.
+
+    Same contract as ``resolve_inject_credential``, for injectors that read
+    the attachment and resolve it at two different stages.
+
+    Raises:
+        CredentialResolutionError: with the code to report in the trace.
+    """
     payload = api.inject.resolve_attachment_secret(
         inject_id, attachment.reference, attachment.authorisation_code
     )
@@ -110,5 +129,6 @@ def resolve_inject_credential(
 __all__ = [
     "CredentialAttachment",
     "get_credential_attachment",
+    "resolve_credential_attachment",
     "resolve_inject_credential",
 ]
@@ -2,10 +2,17 @@
 
 The platform resolution endpoint answers with a closed set of error codes.
 ``CREDENTIAL_INCOMPATIBLE`` is detected by the injector itself, when the
-resolved credential does not satisfy the contract field. Each code carries a fixed, human-readable message meant to be reported as is
-in the inject execution trace. Messages only ever mention the credential
-reference id, never a secret value, and the raw HTTP request and response
-bodies are deliberately never kept on the error.
+resolved credential does not satisfy the contract field, and
+``CREDENTIAL_RESOLUTION_UNAVAILABLE`` when the platform could not be reached or
+failed to answer. Each code carries a fixed, human-readable message meant to be
+reported as is in the inject execution trace. Messages only ever mention the
+credential reference id, never a secret value, and the raw HTTP request and
+response bodies are deliberately never kept on the error.
+
+A message is made of a summary (what happened) followed by a guidance (what to
+do). Both parts are exposed through ``credential_error_summary`` and
+``credential_error_guidance`` so injectors that report them separately reuse
+the exact same texts.
 """
 
 from enum import Enum
@@ -20,6 +27,7 @@ class CredentialErrorCode(str, Enum):
     CREDENTIAL_INACTIVE = "CREDENTIAL_INACTIVE"
     CREDENTIAL_ACCESS_DENIED = "CREDENTIAL_ACCESS_DENIED"
     CREDENTIAL_INCOMPATIBLE = "CREDENTIAL_INCOMPATIBLE"
+    CREDENTIAL_RESOLUTION_UNAVAILABLE = "CREDENTIAL_RESOLUTION_UNAVAILABLE"
 
 
 _PLATFORM_CREDENTIAL_ERROR_CODES = {
@@ -28,43 +36,84 @@ class CredentialErrorCode(str, Enum):
     CredentialErrorCode.CREDENTIAL_ACCESS_DENIED,
 }
 
+UNKNOWN_REFERENCE = "unknown reference"
 
-_CREDENTIAL_ERROR_MESSAGES = {
+_CREDENTIAL_ERROR_SUMMARIES = {
     CredentialErrorCode.CREDENTIAL_NOT_FOUND: (
         "The credential configured on this inject ({reference}) no longer exists "
-        "at the moment of execution. Select an existing credential on the inject, "
-        "then run it again."
+        "at the moment of execution."
     ),
     CredentialErrorCode.CREDENTIAL_INACTIVE: (
-        "The credential {reference} is inactive at the moment of execution. "
-        "Update or replace this credential, then run the inject again."
+        "The credential {reference} is inactive at the moment of execution."
     ),
     CredentialErrorCode.CREDENTIAL_ACCESS_DENIED: (
         "This execution is not entitled to use the credential configured on this "
-        "inject. Contact your Cloud platform administrator"
+        "inject."
     ),
     CredentialErrorCode.CREDENTIAL_INCOMPATIBLE: (
-        "The credential {reference} is not compatible with this inject. Select a "
-        "credential of type {type} on the inject, then run it again."
+        "The credential {reference} is not compatible with this inject."
+    ),
+    CredentialErrorCode.CREDENTIAL_RESOLUTION_UNAVAILABLE: (
+        "The credential {reference} could not be resolved: the OpenAEV platform "
+        "was unavailable at the moment of execution."
+    ),
+}
+
+_CREDENTIAL_ERROR_GUIDANCES = {
+    CredentialErrorCode.CREDENTIAL_NOT_FOUND: (
+        "Select an existing credential on the inject, then run it again."
+    ),
+    CredentialErrorCode.CREDENTIAL_INACTIVE: (
+        "Update or replace this credential, then run the inject again."
+    ),
+    CredentialErrorCode.CREDENTIAL_ACCESS_DENIED: (
+        "Contact your Cloud platform administrator"
+    ),
+    CredentialErrorCode.CREDENTIAL_INCOMPATIBLE: (
+        "Select a credential of type {type} on the inject, then run it again."
+    ),
+    CredentialErrorCode.CREDENTIAL_RESOLUTION_UNAVAILABLE: (
+        "Check that the injector can reach the platform, then run the inject again."
     ),
 }
 
 # Used when the expected credential type is not known where the error is raised
 # (for example an unknown secret type returned by the platform).
-_CREDENTIAL_INCOMPATIBLE_UNKNOWN_TYPE_MESSAGE = (
-    "The credential {reference} is not compatible with this inject. Select a "
-    "credential of the type expected by the inject, then run it again."
+_CREDENTIAL_INCOMPATIBLE_UNKNOWN_TYPE_GUIDANCE = (
+    "Select a credential of the type expected by the inject, then run it again."
 )
 
 
+def credential_error_summary(
+    code: CredentialErrorCode, reference: Optional[str] = None
+) -> str:
+    """Return what happened, mentioning only the reference id."""
+    return _CREDENTIAL_ERROR_SUMMARIES[CredentialErrorCode(code)].format(
+        reference=reference or UNKNOWN_REFERENCE
+    )
+
+
+def credential_error_guidance(
+    code: CredentialErrorCode, expected_type: Optional[CredentialType] = None
+) -> str:
+    """Return what the operator should do about ``code``."""
+    code = CredentialErrorCode(code)
+    if code == CredentialErrorCode.CREDENTIAL_INCOMPATIBLE and expected_type is None:
+        return _CREDENTIAL_INCOMPATIBLE_UNKNOWN_TYPE_GUIDANCE
+    return _CREDENTIAL_ERROR_GUIDANCES[code].format(
+        type=CredentialType(expected_type).value if expected_type else None
+    )
+
+
 def credential_error_code_from_http(
     response_code: Optional[int], error_message: Optional[str]
 ) -> CredentialErrorCode:
     """Map a failed resolution call to its credential error code.
 
     The code sent by the platform in the response ``message`` wins. A 404
     without a known code (the inject itself does not exist) is reported as
-    ``CREDENTIAL_NOT_FOUND``. Any other failure falls back to
+    ``CREDENTIAL_NOT_FOUND``, and a server error as
+    ``CREDENTIAL_RESOLUTION_UNAVAILABLE``. Any other failure falls back to
     ``CREDENTIAL_ACCESS_DENIED`` so that nothing about the credential leaks.
     """
     if error_message:
@@ -76,16 +125,19 @@ def credential_error_code_from_http(
             return code
     if response_code == 404:
         return CredentialErrorCode.CREDENTIAL_NOT_FOUND
+    if response_code is not None and response_code >= 500:
+        return CredentialErrorCode.CREDENTIAL_RESOLUTION_UNAVAILABLE
     return CredentialErrorCode.CREDENTIAL_ACCESS_DENIED
 
 
 class CredentialResolutionError(OpenAEVError):
     """A credential reference could not be resolved for the current execution.
 
-    ``message`` holds the fixed human-readable message of ``code``. The HTTP
-    response body is never stored, so it cannot surface in ``str()``.
-    ``expected_type`` is the credential type the inject expects, only used by
-    the ``CREDENTIAL_INCOMPATIBLE`` message.
+    ``message`` holds the fixed human-readable message of ``code``, which is
+    ``summary`` followed by ``guidance``. The HTTP response body is never
+    stored, so it cannot surface in ``str()``. ``expected_type`` is the
+    credential type the inject expects, only used by the
+    ``CREDENTIAL_INCOMPATIBLE`` message.
     """
 
     def __init__(
@@ -100,18 +152,12 @@ def __init__(
         self.expected_type = (
             CredentialType(expected_type) if expected_type is not None else None
         )
-        template = _CREDENTIAL_ERROR_MESSAGES[self.code]
-        if (
-            self.code == CredentialErrorCode.CREDENTIAL_INCOMPATIBLE
-            and self.expected_type is None
-        ):
-            template = _CREDENTIAL_INCOMPATIBLE_UNKNOWN_TYPE_MESSAGE
-        message = template.format(
-            reference=reference or "unknown reference",
-            type=self.expected_type.value if self.expected_type else None,
-        )
+        self.summary = credential_error_summary(self.code, reference)
+        self.guidance = credential_error_guidance(self.code, self.expected_type)
         super().__init__(
-            error_message=message, response_code=response_code, response_body=None
+            error_message=f"{self.summary} {self.guidance}",
+            response_code=response_code,
+            response_body=None,
         )
 
     @property
@@ -144,9 +190,12 @@ def __init__(self, reference: Optional[str] = None) -> None:
 
 
 __all__ = [
+    "UNKNOWN_REFERENCE",
     "CredentialErrorCode",
     "CredentialResolutionError",
     "InvalidResolvedSecretError",
     "UnsupportedSecretTypeError",
     "credential_error_code_from_http",
+    "credential_error_guidance",
+    "credential_error_summary",
 ]
@@ -16,6 +16,8 @@
 from typing import Callable, Dict, Iterator, List, Optional
 
 from pyoaev.credential.errors import (
+    CredentialErrorCode,
+    CredentialResolutionError,
     InvalidResolvedSecretError,
     UnsupportedSecretTypeError,
 )
@@ -42,6 +44,10 @@
 }
 
 
+class _UnsupportedAzureEnvironmentError(Exception):
+    """The Azure cloud of the credential has no known authority host."""
+
+
 class CredentialCleanupError(RuntimeError):
     """Temporary credential files could not be removed."""
 
@@ -167,7 +173,9 @@ def _azure_authority_host(environment: str) -> str:
     try:
         return AZURE_AUTHORITY_HOSTS[environment]
     except KeyError:
-        raise InvalidResolvedSecretError() from None
+        # A valid platform value (e.g. the retired AzureGermanCloud) the
+        # injectors cannot target: the credential is incompatible, not invalid.
+        raise _UnsupportedAzureEnvironmentError() from None
 
 
 def _azure_service_principal(
@@ -245,27 +253,45 @@ def _gcp_oauth2(secret: GcpOAuth2Secret, workspace: _Workspace) -> Dict[str, str
 
 @contextmanager
 def materialize(
-    resolved: ResolvedSecret, temporary_root: Optional[Path] = None
+    resolved: ResolvedSecret,
+    temporary_root: Optional[Path] = None,
+    *,
+    reference: Optional[str] = None,
 ) -> Iterator[MaterializedCredential]:
     """Materialize ``resolved`` for the duration of the ``with`` block.
 
     Args:
         resolved: the secret returned by ``resolve_inject_credential``.
         temporary_root: parent of the private directory, the system temporary
             directory when omitted.
+        reference: the credential reference id, only used in error messages.
 
     Raises:
         UnsupportedSecretTypeError: the secret type is not a cloud credential
             (``USERNAME_PASSWORD``, ``HASH``).
+        CredentialResolutionError: ``CREDENTIAL_INCOMPATIBLE`` when the Azure
+            cloud of the credential cannot be targeted.
         InvalidResolvedSecretError: a value cannot be materialized safely.
         CredentialCleanupError: the temporary files could not be removed.
     """
     materializer = _MATERIALIZERS.get(resolved.secret_type)
     if materializer is None:
-        raise UnsupportedSecretTypeError(resolved.secret_type.value)
+        raise UnsupportedSecretTypeError(resolved.secret_type.value, reference)
     workspace = _Workspace(temporary_root)
+    error: Optional[CredentialResolutionError] = None
     try:
-        env = materializer(resolved, workspace)
+        # Raised outside of the except blocks so that no original error, which
+        # may quote a secret value, is chained to the reported one.
+        try:
+            env = materializer(resolved, workspace)
+        except _UnsupportedAzureEnvironmentError:
+            error = CredentialResolutionError(
+                CredentialErrorCode.CREDENTIAL_INCOMPATIBLE, reference
+            )
+        except InvalidResolvedSecretError:
+            error = InvalidResolvedSecretError(reference)
+        if error is not None:
+            raise error
         yield MaterializedCredential(
             secret_type=resolved.secret_type, env=env, files=list(workspace.files)
         )
 
@@ -132,14 +132,23 @@ def test_unknown_failures_fall_back_to_access_denied(self):
         for response in (
             build_response(401, {"message": "Unauthorized"}, "Unauthorized"),
             build_response(400, {"message": "attachment_id: must not be blank"}),
-            build_response(500, {"message": "boom"}, "Internal Server Error"),
-            build_response(502, None, "Bad Gateway"),
         ):
             with self.subTest(status_code=response.status_code):
                 self._assert_resolution_error(
                     response, CredentialErrorCode.CREDENTIAL_ACCESS_DENIED
                 )
 
+    def test_server_errors_are_resolution_unavailable(self):
+        for response in (
+            build_response(500, {"message": "boom"}, "Internal Server Error"),
+            build_response(502, None, "Bad Gateway"),
+        ):
+            with self.subTest(status_code=response.status_code):
+                error = self._assert_resolution_error(
+                    response, CredentialErrorCode.CREDENTIAL_RESOLUTION_UNAVAILABLE
+                )
+                self.assertNotIn("boom", error.message)
+
     def test_non_json_success_is_access_denied(self):
         response = requests.Response()
         response.status_code = 200
@@ -150,7 +159,7 @@ def test_non_json_success_is_access_denied(self):
             response, CredentialErrorCode.CREDENTIAL_ACCESS_DENIED
         )
 
-    def test_network_error_is_access_denied(self):
+    def test_network_error_is_resolution_unavailable(self):
         api_client = OpenAEV("url", "token")
         with mock.patch(
             "requests.Session.request",
@@ -162,7 +171,8 @@ def test_network_error_is_access_denied(self):
                 )
 
         self.assertEqual(
-            context.exception.code, CredentialErrorCode.CREDENTIAL_ACCESS_DENIED
+            context.exception.code,
+            CredentialErrorCode.CREDENTIAL_RESOLUTION_UNAVAILABLE,
         )
 
     def test_error_never_exposes_response_body(self):