Errors and rate limits

Error responses

Every failure is application/problem+json. Branch on code, which is stable across wording changes; detail is prose and may be reworded.

{
  "type": "https://stride.is/docs/api/errors#insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This endpoint requires the metrics.read scope, which this token does not hold.",
  "code": "insufficient_scope"
}

What each status means

• 400
  invalid_request

  A malformed date, an unknown enum value, or an unrecognised field in the body. We reject unknown fields rather than ignoring them, so a misspelled key is reported instead of silently doing nothing.

• 401
  unauthenticated

  No token, an expired one, or one minted for a different resource. An MCP token is not accepted here and vice versa.

• 402
  subscription_required

  The Stride account the token belongs to has no active subscription or trial.

• 403
  insufficient_scope / forbidden

  The token lacks the scope, or may not act on the athlete or team named.

• 404
  not_found

  No such resource, or it is not visible to this token. The two are deliberately indistinguishable so the ID space cannot be probed.

• 405
  method_not_allowed

  The path exists but not for that verb. The Allow header lists the ones it serves.

• 422
  unprocessable

  Understood but impossible to carry out, most often an upload that produced no activity.

• 429
  rate_limited

  A limit was exceeded. Retry after the period in the Retry-After header.

Rate limits

Two windows, a short one and a daily one, applied per app and again per app-and-athlete. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds), so you can back off before you are refused rather than discovering the limit by hitting it.