Error model
Lamba endpoints use one of two patterns:
- ProblemDetails-style payloads for API validation and access failures.
- Plan-limit contract payload for billing and quota enforcement.
ProblemDetails shape
{
"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 shape (402)
{
"error": "PLAN_LIMIT_EXCEEDED",
"limit": "mau",
"allowed": 5000,
"current": 5001,
"plan": "free",
"message": "Plan limit exceeded. Upgrade to continue."
}
Common statuses
| Status | Typical reason | What to do |
|---|---|---|
401 | Invalid or missing credentials | Refresh session or re-authenticate user |
403 | Tenant/project scope mismatch or blocked access | Verify membership, role, and tenant context |
429 | Rate limit exceeded | Respect Retry-After, backoff, retry safely |
402 | Plan limit enforcement | Upgrade plan or reduce usage to within limits |
5xx | Service-side failure | Retry with jitter and include traceId in support ticket |
Operational guidance
- Always log
errorCodeandtraceId. - Treat
402as a product/billing state, not a transient transport error. - For
429, implement bounded retries with exponential backoff. - For repeated
5xx, capture request metadata and contact support.