Why do all my tasks fail with a 401 or 403 even though the queue shows them as dispatched?

This is almost always the oidcToken configuration: either serviceAccountEmail lacks roles/run.invoker (or the Cloud Functions equivalent) on the target, or audience doesn't exactly match the target URL Cloud Tasks is calling. Check both — a mismatched audience produces the same symptom as a missing IAM binding, but requires a different fix.

What's the difference between maxDispatchesPerSecond and maxConcurrentDispatches?

maxDispatchesPerSecond throttles the rate of new attempts starting; maxConcurrentDispatches caps how many are in-flight (started but not yet completed) at once. A slow-responding backend can hit the concurrency cap and stall new dispatches even while comfortably under the per-second rate limit, they're independent constraints and both matter for throughput tuning.

Does the body field need to be base64-encoded?

Yes, httpRequest.body in the Cloud Tasks API is bytes, so JSON payloads must be base64-encoded before being placed in the task, not sent as raw JSON text. Client libraries handle this encoding automatically when you pass a plain object or string; hand-constructing the API payload is where this gets missed.

GCP Cloud Tasks HTTP Target Builder

ServerlessGCP

Build Cloud Tasks HTTP target configurations with OIDC authentication, rate limits, and retry policies.

Cloud Tasks Configuration

Build Cloud Tasks HTTP target configurations with OIDC authentication, rate limits, retry policies, and dispatch scheduling.

Required Fields

parenttask.httpRequest.urltask.httpRequest.httpMethod

{
  "parent": "projects/my-project/locations/us-central1/queues/order-processing",
  "task": {
    "name": "projects/my-project/locations/us-central1/queues/order-processing/tasks/order-12345",
    "httpRequest": {
      "url": "https://orders-service-abc123-uc.a.run.app/process",
      "httpMethod": "POST",
      "headers": {
        "Content-Type": "application/json",
        "X-Request-Id": "order-12345"
      },
      "body": "eyJvcmRlcklkIjoiMTIzNDUiLCJhY3Rpb24iOiJwcm9jZXNzIn0=",
      "oidcToken": {
        "serviceAccountEmail": "tasks-invoker@my-project.iam.gserviceaccount.com",
        "audience": "https://orders-service-abc123-uc.a.run.app"
      }
    },
    "scheduleTime": "2026-03-15T10:00:00Z",
    "dispatchDeadline": "1800s"
  },
  "queueConfig": {
    "rateLimits": {
      "maxDispatchesPerSecond": 100,
      "maxBurstSize": 50,
      "maxConcurrentDispatches": 20
    },
    "retryConfig": {
      "maxAttempts": 5,
      "maxRetryDuration": "3600s",
      "minBackoff": "5s",
      "maxBackoff": "300s",
      "maxDoublings": 4
    },
    "stackdriverLoggingConfig": {
      "samplingRatio": 1.0
    }
  }
}

Generated Output

Output will appear here...

About This Tool

Build a Cloud Tasks HTTP target task and queue configuration, covering OIDC-authenticated dispatch to a backend, rate limits, and retry policy. maxDispatchesPerSecond defaults to 500/s per queue (raisable via quota request), maxConcurrentDispatches bounds in-flight tasks independent of dispatch rate, and dispatchDeadline (default 1800s / 30 minutes, capped there) is the window Cloud Tasks waits for a response before considering the attempt failed and retrying per retryConfig. The oidcToken block is what actually authenticates the request to a Cloud Run or Cloud Functions target, without it a task hitting an ingress-restricted backend gets a 401/403 that has nothing to do with the task payload itself.

Real-World Scenario

A team enqueues thousands of order-confirmation tasks against a Cloud Run endpoint during a flash sale, and within minutes the queue's dashboard shows a huge backlog of failed attempts, all 403. The team hadn't changed the task config, but a separate security hardening pass earlier that week had tightened the target service's IAM policy and inadvertently removed the Cloud Tasks queue's invoker binding during a broader cleanup. They use the builder to confirm the oidcToken.serviceAccountEmail is unchanged and correctly scoped, re-grant roles/run.invoker to that service account on the target service, and the backlog of failed tasks starts draining automatically as Cloud Tasks retries them per the existing retryConfig.

When to Use This Tool

•Debugging a queue where tasks are dispatching but every attempt gets 403 from the target Cloud Run service, tracing it back to the oidcToken.serviceAccountEmail lacking roles/run.invoker on that specific service.
•Lowering maxDispatchesPerSecond on a queue calling a rate-limited third-party API, so Cloud Tasks self-throttles instead of the downstream API rejecting bursts with its own 429s.
•Tuning retryConfig's maxDoublings and maxBackoff so a downstream outage produces a controlled backoff curve instead of either giving up too fast or hammering the recovering service.
•Setting scheduleTime on a task to delay execution to a specific future timestamp, for a workflow step that needs to run after a fixed cooldown rather than immediately on enqueue.

Pro Tips

TIP

dispatchDeadline caps at 1800s (30 minutes) — a task calling a genuinely long-running backend operation needs a different pattern (e.g., dispatch a request that starts async work and returns immediately) rather than trying to raise this past its hard limit.

TIP

Retrying with maxDoublings set too low against a long-running outage causes backoff to plateau at a low ceiling quickly, meaning constant retry pressure on a downstream service that's still down, tune maxBackoff and maxDoublings together, not independently.

TIP

A queue-level rate limit change takes effect only for new dispatches, tasks already scheduled under the old rate configuration keep their existing schedule rather than being retroactively re-throttled.

How It Works Under the Hood

The builder requires parent, task.httpRequest.url, and task.httpRequest.httpMethod to resolve, the minimum needed to know which queue owns the task and where it's headed; the OIDC auth block, rate limits, and retry policy are validated as well-formed JSON but their correctness against your actual backend's IAM and capacity is on you to verify.

Frequently Asked Questions

Why do all my tasks fail with a 401 or 403 even though the queue shows them as dispatched?: This is almost always the oidcToken configuration: either serviceAccountEmail lacks roles/run.invoker (or the Cloud Functions equivalent) on the target, or audience doesn't exactly match the target URL Cloud Tasks is calling. Check both — a mismatched audience produces the same symptom as a missing IAM binding, but requires a different fix.
What's the difference between maxDispatchesPerSecond and maxConcurrentDispatches?: maxDispatchesPerSecond throttles the rate of new attempts starting; maxConcurrentDispatches caps how many are in-flight (started but not yet completed) at once. A slow-responding backend can hit the concurrency cap and stall new dispatches even while comfortably under the per-second rate limit, they're independent constraints and both matter for throughput tuning.
Does the body field need to be base64-encoded?: Yes, httpRequest.body in the Cloud Tasks API is bytes, so JSON payloads must be base64-encoded before being placed in the task, not sent as raw JSON text. Client libraries handle this encoding automatically when you pass a plain object or string; hand-constructing the API payload is where this gets missed.

Related Learning Guides

Cloud Functions vs Cloud Run24 min read
Pub/Sub & Event-Driven Architecture25 min read

Was this tool helpful?

Disclaimer: This tool runs entirely in your browser. No data is sent to our servers. Always verify outputs before using them in production. AWS, Azure, and GCP are trademarks of their respective owners.