Troubleshooting

403 Forbidden right after a deploy

For a minute or two after a tenant stack is created or updated, valid tokens can get 403 Forbidden or Invalid key=value pair … in Authorization header while API Gateway propagates new routes and usage plan to API key links. Wait and retry.

401 Unauthorized from the tenant API

• The token is from a different user pool. A Platinum tenant’s token only works on its own silo API, and a pooled tenant’s token only works on the pooled API.
• The token is an access token. The API needs the ID token, which carries the tenant claims.
• The token expired. ID tokens last an hour.
• The user’s tier isn’t served by this stack. The authorizer logs No tenant id or no API key for tier ….

403 on my own product or order

The ownership check compares the key’s shard with the token’s tenant. If a client sends a key that’s still URL-encoded, the shard doesn’t match. tenant_data.split_key decodes keys, so this only happens with a custom client that double-encodes.

429 Too Many Requests

The tenant hit its tier’s rate or daily quota. See Tiers. Move the tenant to a higher tier, or raise the plan’s limits in tiers.ts.

Unknown tenant in the SaaS app

GET /tenant-config/{name} found no tenant with that name. Check the name in the admin console. Provisioning must be Complete before the tenant config exists.

Provisioning stays In progress

Open the provisioning state machine in Step Functions and the CodeBuild build it started, in the serverless-saas-bootstrap stack. A Platinum tenant takes about 8 minutes because the job runs npm ci, CDK synth, Docker bundling and a CloudFormation deploy.

No export named ControlPlaneStack:ExportsOutput…

The bootstrap stack imports the event bus ARN from the control plane. Deploy ControlPlaneStack first, or use deploy.sh, which deploys everything in order.

The pipeline ran with old code

A new CodePipeline runs once as soon as it’s created, with whatever source.zip is in the bucket. Run ./scripts/upload-source.sh to start a run with the current code.

Custom domain deploy fails

• Found zones: [] for dns:…: DOMAIN_NAME must be a public hosted zone in the same account.
• Certificate stuck in validation: check that the zone’s name servers match the domain’s registrar settings.
• Region error: the certificate must be in us-east-1 for CloudFront, so deploy the client stack there.