AWS API Gateway Error: Lambda Integration Permission Errors

#aws#apigateway#devops#cloud

How to diagnose and fix API Gateway requests that fail because Lambda invocation permissions are missing, mis-scoped, or incorrectly bound to stages, methods, source ARNs, or function aliases

Problem

You invoke an endpoint exposed through Amazon API Gateway. The route exists, authorization succeeds, but the request fails at runtime.

What the client usually sees

When calling the API via curl, Postman, or a browser, the response is often just:

{
  "message": "Internal server error"
}

With an HTTP status code of:

500 Internal Server Error

What the logs or Test Console reveal

In API Gateway execution logs or the Test console, you see the real cause:

Execution failed due to configuration error:
API Gateway does not have permission to invoke the Lambda function

This mismatch often causes engineers to chase Lambda bugs or runtime issues, when the failure is actually a permission problem.

---

Clarifying the Issue

This error occurs after routing and authorization succeed, but before Lambda is invoked.

The failure lives at the integration boundary between API Gateway and Lambda.

In plain terms:

✅ API Gateway knows where to send the request
✅ Authorization allowed the request
✅ Lambda exists and is healthy
❌ But Lambda refuses the invocation

This happens when the Lambda function’s resource policy does not explicitly allow API Gateway to invoke it.

---

Why It Matters

This is one of the most common API Gateway failures in Infrastructure as Code environments.

Why?

• The AWS Console automatically creates the required permission when you add a Lambda trigger.

• Terraform, CDK, and CloudFormation do not.

  • You must explicitly create an AWS::Lambda::Permission (or equivalent).

As a result:

• The API deploys cleanly
• Authorization works
• Lambda tests fine in isolation
• Real traffic fails with a generic 500

If you don’t recognize this pattern, you’ll debug the wrong layer indefinitely.

---

Key Terms

• Integration – The backend target for an API Gateway route
• Lambda Resource Policy – A policy attached directly to the function
• lambda:AddPermission – Grants another AWS service permission to invoke the function
• Source ARN – The API Gateway ARN allowed to invoke the function
• Function Alias – A versioned Lambda reference (my-function:prod)

---

Steps at a Glance

1. Confirm this is an integration-stage failure
2. Understand the API Gateway → Lambda trust boundary
3. Inspect the Lambda resource policy
4. Validate the Source ARN and function alias
5. Add or correct the invocation permission
6. Retest the integration

---

Detailed Steps

Step 1: Confirm This Is an Integration Error

You are in the right Fix-It if:

• Routing succeeds (no Missing Authentication Token)
• Authorization succeeds (no 403)
• The client sees a 500 Internal Server Error
• API Gateway logs reference invalid Lambda permissions

If the logs mention invocation permissions, stop debugging Lambda code.

---

Step 2: Understand the Trust Boundary

API Gateway does not invoke Lambda using your IAM role.

Instead:

• API Gateway is an AWS service principal
• Lambda enforces its own resource policy
• Invocation is denied unless explicitly allowed

Even if:

• You own the function
• You can invoke it manually
• IAM roles look permissive

Lambda will still reject API Gateway without a proper permission entry.

---

Step 3: Inspect the Lambda Resource Policy

Retrieve the policy:

aws lambda get-policy \
  --function-name my-function

If:

• No policy exists, or
• No statement allows apigateway.amazonaws.com

Then API Gateway cannot invoke the function.

---

Step 4: Validate the Source ARN (Most Common Failure)

A typical permission uses a Source ARN like:

arn:aws:execute-api:region:account-id:api-id/stage/HTTP-VERB/resource

Common real-world mistakes:

• Stage mismatch (dev vs prod)
• Missing wildcards for methods or paths
• Old API ID after recreating the API

• Function alias mismatch:

  • API targets my-function:prod
  • Permission exists only on my-function ($LATEST)

Permissions must match the exact function reference being invoked.

---

Step 5: Add or Correct the Permission

A debugging-safe permission:

aws lambda add-permission \
  --function-name my-function \
  --statement-id apigateway-invoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn arn:aws:execute-api:region:account-id:api-id/*/*/*

Important:

• This permission is attached to the Lambda function
• Not to IAM roles
• Not to API Gateway

You can tighten the scope once the integration is confirmed working.

---

Step 6: Retest the Integration

• Re-run the HTTP request
• No redeploy is required
• The fix takes effect immediately

If permissions are correct, the 500 disappears and Lambda executes normally.

---

Pro Tips

• A 500 here usually means permissions, not code.
• Console-created APIs “just work”; IaC does not add permissions automatically.
• Function aliases matter. Permissions must match the alias.
• Recreating an API invalidates old Source ARNs.
• Check the Lambda policy before touching IAM roles.

---

Conclusion

Lambda integration permission errors occur at a precise boundary:

✅ Routing worked
✅ Authorization worked
❌ Integration failed

API Gateway attempted to invoke Lambda, and Lambda rejected the call.

Once you recognize this as a resource policy problem, the fix becomes deterministic:
inspect the policy, validate the Source ARN (and alias), and explicitly grant invocation rights.

No guesswork. No redeploys. Just a contract that must be honored.

---

Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.