Terraform Cloud "returned an unexpected error" 429 rate limit in CI

HCP Terraform enforces a per-token API rate limit. When a burst of CI jobs sharing one token exceeds it, the API returns 429 and the CLI surfaces it as an unexpected error. This is transient and clears once the window resets.

What this error means

A run or state call fails with "HCP Terraform returned an unexpected error" and an HTTP 429 / "too many requests" status, often when many workspaces run at once.

Error: HCP Terraform returned an unexpected error

  unexpected HTTP status code: 429 Too Many Requests

Common causes

Many concurrent jobs share one token

A matrix or fan-out pipeline using a single token can exceed the per-token request limit during a burst.

Tight polling or retries amplify request volume

Frequent status polling or aggressive retries multiply calls and push the token over the limit.

How to fix it

Back off and retry

1. Treat 429 as retryable and wait before retrying.
2. Reduce concurrency so fewer jobs hit the API at once.
3. Re-run once the rate window resets.

concurrency:
  group: terraform-cloud-${{ github.ref }}
  cancel-in-progress: false

Spread load across tokens

Use separate team tokens for independent pipelines so no single token carries all the request volume.

How to prevent it

• Cap parallel Terraform Cloud jobs that share a token.
• Use distinct team tokens for large fan-out pipelines.
• Avoid tight status polling loops against the API.

Related guides