Troubleshooting

Find logs for one request

Use requestId from the error JSON, response header x-request-id, or the web client error object. Async jobs copy the same id on the SQS message attribute into Lambda logs.

In CloudWatch Logs Insights, filter JSON where requestId matches, optionally with service:

service	Workload
sophia-api	Fargate API
sophia-interview-completed	Settlement Lambda
sophia-report-generate	Report Lambda

Look for request.completed / request.failed (status, duration, path) or central logs Unhandled error (5xx) / Request rejected (4xx). If the id is unknown, the failure likely happened before observability middleware or without async context.

Health

curl -sS "$BASE_URL/health" | jq .
pnpm smoke

/health is always HTTP 200; degraded means Mongo is down while the process is up. ALB uses the same path—502/503 with local smoke OK often means targets or deploy, not the health JSON alone.

Quick fixes

Symptom	Check
401/403	Token, user status, suspended org
No settlement	Unset queue URL (API warn); SQS/DLQ
Report stuck	Report queue backlog; Lambda ERROR + DLQ
Mongo issues	mongo.connection_failed; stage URI
Stripe	Webhook secret and signature logs

DLQ messages need manual inspect/redrive after root-cause fix. Schema-invalid SQS bodies are dropped and do not DLQ via retry.