Error model
Lamba customer surfaces use RFC7807 ProblemDetails as the single error shape. Business-state details such as plan limits are added as extension fields.
{
"type": "https://api.uselamba.com/problems/authorization",
"title": "Forbidden",
"status": 403,
"detail": "The current principal cannot access this resource.",
"errorCode": "AUTHORIZATION_DENIED",
"traceId": "00-2f7b4a..."
}
Plan limit example (402 PLAN_LIMIT_EXCEEDED)
{
"type": "https://api.uselamba.com/problems/plan-limit",
"title": "Plan limit exceeded",
"status": 402,
"detail": "The workspace has exceeded its monthly active user limit.",
"errorCode": "PLAN_LIMIT_EXCEEDED",
"limit": "mau",
"allowed": 5000,
"current": 5001,
"plan": "free",
"traceId": "00-8a5f0f..."
}
Remediation table
| Status | Typical reason | Remediation |
|---|---|---|
401 | Missing or invalid auth credentials | Re-authenticate, refresh session, verify token audience and issuer |
403 | Role, policy, or context mismatch | Verify membership, active project context, and required permission |
429 | Rate limit exceeded | Respect Retry-After, apply bounded backoff, retry idempotent calls |
402 | Plan or usage limit reached | Upgrade plan or reduce usage; treat as business-state response |
5xx | Service-side failure | Retry with jitter and bounded attempts; include traceId in support tickets |
Logging requirements
Always log:
statuserrorCodetraceId- request route and resolved workspace/project context when available