Errors and limits

#The error envelope

Every error the API raises on purpose has the same JSON shape (errorResponseSchema):

{
  "errorCode": "PLAN_LIMIT_REACHED",
  "message": "The free plan allows 10 connectedMembers",
  "details": { "limit": "connectedMembers", "tier": "free", "max": 10 }
}

• errorCode is a LatidoErrorCode (exported by @latido/common and @latido/sdk). Branch on it, not on message, which is for humans and may change.
• details appears only on some errors (today: PLAN_LIMIT_REACHED).
• Two responses do not carry an errorCode: an unknown route (404 {"message":"Not Found"}) and an unhandled server failure (500 {"message":"Internal Server Error"}). The SDK raises LatidoApiError with code: undefined for them.
• No request-id header is sent today; LatidoApiError.requestId is read from Latido-Request-Id / X-Request-Id / Request-Id for when one is.

With the SDK, every non-2xx becomes a LatidoApiError (status, code, message, details, retryAfterSeconds, body); see the SDK reference for the other error classes.

#Error codes of the public API

The full enum, including codes only the dashboard and hosted flow use, is exported by the SDK as LatidoErrorCode.

#Plan limits

Plan limits apply the same way to REST and MCP.

Lifetime tiers come from AppSumo licenses (one license, one tier). They never include Latido's managed apps for providers that charge or gate partners (Garmin, Oura, WHOOP, Dexcom, Google Health): those work with your own keys on every tier.

• Connected members counts live members with at least one active connection; test members never count. A member already connected does not count twice. Reaching the limit fails the connect callback with reason=plan_limit_reached and an ingest upload with 403 PLAN_LIMIT_REACHED.
• PLAN_LIMIT_REACHED carries details: { limit, tier, max }; limit is a PlanLimitName (projects, connectedMembers, apiRequestsPerMonth, webhookEndpoints, teamSeats, customProviderApps, mcp, plannedWorkouts); for yes/no features max is false.
• The dashboard shows usage (GET /dashboard/usage) and the plan (GET /dashboard/billing).

#Rate limits

• Monthly quota. Every authenticated /v1 and /mcp request counts (a Redis counter per account and calendar month, UTC). The one over the quota is refused with 429 PLAN_LIMIT_REACHED and not counted. No Retry-After is sent: waiting a few seconds does not help, so the SDK does not retry it.
• Resync. POST /v1/connections/{id}/sync runs at most once per connection every 5 minutes (429 RESYNC_RATE_LIMITED, not retried by the SDK).
• No per-second limit is enforced by the API today. If a proxy in front of the API ever adds one, its 429s (with or without Retry-After) are retried by the SDK.
• Timeouts. Every route answers within 60 seconds.

#Request limits

#Retrying safely

• GET and DELETE are safe to repeat. So are POST /v1/members (an upsert by externalUserId), POST /v1/connect/sessions (a repeat only makes another link), POST /v1/connections/{id}/sync (a repeat is refused with RESYNC_RATE_LIMITED) and ingest (idempotent by providerRecordId).
• POST /v1/members/{id}/planned-workouts is not: a repeat pushes a second workout. Retry it only after 423 / 429, which mean nothing was done.
• 423 and 429 (except the two persistent 429s above) mean the request was refused before any work. 5xx and timeouts mean it may or may not have happened.

The SDK applies exactly these rules (exponential backoff with jitter, Retry-After honoured up to maxRetryDelayMs).