Errors and retries

Errors and retries are the states your deployment card shows when a cloud call fails. They apply when you launch the portal from your product with a Deploy button, and when you build it into your product with your own setup screen.

Show the cloud's real error, under the resource it belongs to, with the fix. "Something went wrong" sends every failure to your support queue.

Automatic retriesCopy Anchor Link

Alien retries failed cloud calls on its own. Most first failures are noise: an API that wasn't ready yet, or a permission that hadn't propagated.

While retryAttempt is 1, the page looks the same as before:

Show it when a resource has an error, retryAttempt is 1, and the resource's status doesn't end in -failed.

• Hide the first error. Cloud APIs fail once all the time, and the next attempt usually succeeds.
• Keep it findable. Put the error in a details view and in your logs, so support can see it.
• Agents and APIs. Hide it only in the human view. Anything your product exposes to automation should pass the error through.

{
  "status": "provisioning",
  "resources": [
    {
      "id": "compute",
      "displayName": "Compute cluster",
      "type": "compute-cluster",
      "status": "provisioning",
      "error": {
        "code": "CLOUD_PLATFORM_ERROR",
        "message": "Could not read the security group for the machines: AWS reported it missing.",
        "retryable": true
      },
      "retryAttempt": 1
    }
  ]
}

When the same resource fails again, show the error under it and say Alien is retrying:

Show it when the same resource still has an error and retryAttempt is 2 or more.

• Inline, updated in place. Show the error under its resource. A toast per poll stacks copies of the same message.
• Say Alien is retrying. Otherwise someone clicks Retry while a retry already runs.
• Recovery. retryAttempt returns to 0 after a success. Remove the message on the next poll.
• Stopped retrying. A status that ends in -failed means Alien stopped. Show the error at once, as in Failed.

{
  "status": "provisioning",
  "resources": [
    {
      "id": "compute",
      "status": "provisioning",
      "error": {
        "code": "CLOUD_PLATFORM_ERROR",
        "message": "Could not read the security group for the machines: AWS reported it missing.",
        "retryable": true
      },
      "retryAttempt": 2
    }
  ]
}

FailedCopy Anchor Link

A failed deployment has error with message (show it), code (branch on it), hint (a suggested fix), and retryable. Each failed resource has its own error too. The example at the top of this page shows this state.

Show it when status ends in -failed (preflights-failed, initial-setup-failed, provisioning-failed, update-failed, refresh-failed) or is error.

• First failure first. List the failed resource at the top, with its error. Resources that stopped because of it come after.
• Customer fixes. When the fix is in the customer's account, such as a quota or a permission, say what to do before you offer Retry.
• Retry requested. After Retry, keep the failure on screen as "Retry requested" while retryRequested is true.
• Not retryable. When error.retryable is false, hide Retry and offer support.
• Update failures. update-failed leaves the previous release running. Say so, and don't show the service as down.

{
  "status": "provisioning-failed",
  "retryRequested": false,
  "error": { "code": "RESOURCE_FAILED", "message": "Compute cluster failed.", "retryable": true },
  "resources": [
    {
      "id": "compute",
      "displayName": "Compute cluster",
      "status": "provision-failed",
      "error": {
        "code": "CLOUD_PLATFORM_ERROR",
        "message": "You have requested more vCPU capacity than your current vCPU limit of 32 allows for the instance bucket that the specified instance type belongs to.",
        "hint": "Raise the Running On-Demand Standard instances quota in us-east-1, or choose a smaller machine type.",
        "retryable": true
      },
      "retryAttempt": 0
    }
  ]
}

Retry is POST /v1/deployments/{id}/retry:

import { alien } from "./alien"

export const retryDeployment = (id: string) => alien.deployments.retry({ id })

Retry accepts the request and returns 202 at once. Read the deployment again to follow it.

Error copyCopy Anchor Link

• Your headline is your own sentence: "Ask your AWS admin to raise the EC2 vCPU quota for us-east-1, then retry."
• The cloud's message under the resource. Show error.message there, and put error.code and the full error behind Error details.
• Update in place. A toast per poll stacks copies of the same message.
• The first failed resource, not the ones that stopped because of it.
• No Retry when error.retryable is false, or when the fix belongs to the customer and isn't done.

Status messages has the words to use for each state.

Test itCopy Anchor Link

• Replay a retry. Return the same error with retryAttempt 1, then 2. The main view stays quiet on 1 and shows one inline message on 2.
• Hit a quota. Choose a size above the test account's vCPU quota, and check your page names the quota and the admin before it offers Retry.
• Retry. Click Retry and confirm the page shows "Retry requested" until the status changes.

NextCopy Anchor Link

• Show deployment progress: every state before ready
• Status messages: the words to use
• Debug a deployment: when your team must act