Introduction

When AWS Lambda fails to return a PDF through API Gateway, the issue is usually binary handling, not PDF generation itself. API Gateway needs binary-aware configuration and Lambda must return correctly encoded payloads. Without this, PDF bytes can be corrupted or interpreted as plain text.

Return Binary Content Correctly from Lambda

For proxy integrations, return Base64-encoded body and set isBase64Encoded to true.

1import base64
2
3def handler(event, context):
4    with open('/tmp/sample.pdf', 'rb') as fh:
5        pdf_bytes = fh.read()
6
7    return {
8        "statusCode": 200,
9        "headers": {
10            "Content-Type": "application/pdf",
11            "Content-Disposition": "inline; filename=report.pdf"
12        },
13        "isBase64Encoded": True,
14        "body": base64.b64encode(pdf_bytes).decode("ascii")
15    }

If isBase64Encoded is false or omitted, gateway can treat bytes as UTF-8 text and break the file.

Configure API Gateway for Binary Media

API Gateway must allow binary media for PDF responses. In REST API mode, add application/pdf to binary media types and redeploy the stage. In HTTP API mode, verify integration and response handling for binary payload passthrough.

Also check gateway and Lambda timeout settings. Large PDF generation can exceed default limits and produce truncated or failed responses.

Stream from S3 Instead of Generating in Function

If PDFs are pre-generated, returning signed URLs is often better than proxying bytes through Lambda. This reduces payload size pressure and improves latency.

1import boto3
2
3s3 = boto3.client("s3")
4
5def get_download_url(bucket, key):
6    return s3.generate_presigned_url(
7        "get_object",
8        Params={"Bucket": bucket, "Key": key},
9        ExpiresIn=300,
10    )

Presigned URLs are a strong option for large documents and heavy traffic endpoints.

Validate Response Headers and Client Behavior

Clients need proper headers to render or download PDF content. Confirm Content-Type and Content-Disposition values, and verify no middleware rewrites them. Browser behavior can differ if file names or disposition are invalid.

For debugging, test with curl and save output to file. If the saved file cannot be opened, compare raw response size and Base64 decode path.

curl -sS "https://api.example.com/report" -o out.pdf
file out.pdf

This isolates server-side correctness from browser-specific behavior.

End-to-end Troubleshooting Checklist

When PDFs still fail after Base64 fixes, validate each hop in isolation. First confirm generated bytes form a valid PDF locally. Then verify Lambda response JSON includes correct flags and headers. Finally inspect API Gateway integration response and client behavior separately.

A reliable debug sequence:

• Log raw byte length before encoding.
• Log Base64 output length and ensure it is non-zero.
• Call Lambda directly with test event and inspect returned object.
• Call API endpoint with curl and compare resulting file size.

1import base64
2
3def validate_pdf(pdf_bytes: bytes) -> None:
4    if not pdf_bytes.startswith(b"%PDF"):
5        raise ValueError("invalid pdf header")
6    encoded = base64.b64encode(pdf_bytes).decode("ascii")
7    decoded = base64.b64decode(encoded)
8    assert decoded.startswith(b"%PDF")

This validation catches upstream generation issues that can be misdiagnosed as API Gateway configuration faults.

Security and Delivery Considerations

If documents are sensitive, avoid caching at shared proxies and set appropriate cache-control headers. For downloadable statements or invoices, consider short-lived signed URLs so access control remains explicit and auditable.

Capture structured logs for request IDs and document keys so failed downloads can be traced quickly in CloudWatch.

Consistent observability reduces recovery time during incidents.

Common Pitfalls

• Returning raw bytes in JSON response body without Base64 encoding.
• Omitting isBase64Encoded when API Gateway expects binary flags.
• Forgetting to enable application/pdf binary handling in API Gateway.
• Generating large PDFs in Lambda without tuning timeout and memory.
• Ignoring response headers required for proper client rendering.

Summary

• Lambda PDF failures are commonly binary transport configuration issues.
• Return Base64 body with isBase64Encoded=true for proxy integrations.
• Enable PDF as binary media type in API Gateway and redeploy.
• Consider presigned S3 URLs for large or frequently downloaded files.
• Validate end-to-end with CLI tools before browser-level debugging.