Skip to content
Developers

Walk15 Connect V1

Errors and limits

Status codes, error bodies, rate limits, Retry-After and what to do in each case.

Walk15 Connect returns fixed error codes with fixed messages. Messages never include your request data, so log the code, HTTP status and X-Request-ID. Never log tokens or response bodies containing user data.

Error formats

WhereFormat
GET /oauth/authorize (browser)Generic Walk15 HTML error page, status 400 (503 when temporarily unavailable, 500 on a server error). Never redirected to your callback.
User cancels consentRedirect to your callback with error=access_denied&state=…
Token and revoke endpoints{ "error": "<code>", "error_description": "<fixed text>" }
Activity and disconnect endpoints{ "error": { "code": "<code>", "message": "<fixed text>" }, "request_id": "<uuid>" }

A GET to any other /connect-walk15/v1/ path returns 404 not_found in the activity error format. Other unsupported paths or HTTP methods may return a different error body, usually with status 404. Check the endpoint path and HTTP method before retrying.

Authorization errors

These appear to the user as "Unable to connect with Walk15". You do not receive them; check your configuration if users report this page.

CauseCheck
invalid_requestEvery parameter present exactly once; redirect_uri identical to the registered value; state 22–2048 visible ASCII characters; 43-character S256 code_challenge; request not older than 10 minutes
unauthorized_clientClient ID is correct for this environment and your client is active (a client_id that is not a UUID is invalid_request)
unsupported_response_typeresponse_type=code
invalid_scopeScopes are known, unique, single-space separated and within your allowance

OAuth endpoint errors

CodeStatusMeaningWhat to do
invalid_request400Malformed body, wrong content type, unknown or duplicate fields, query string present, client credentials in the body, missing or invalid application_user_id on code exchangeFix the request; do not retry unchanged
invalid_client401Client authentication failed: missing or repeated Authorization header, wrong ID or secret, replaced secret, disabled client, wrong environmentFix credentials; contact Walk15 if your client may have been disabled. User re-consent does not help.
invalid_grant400Code or refresh token unknown, expired, used, revoked or not yours; wrong redirect_uri or verifier; connection changed; application_user_id already connected to another Walk15 account, or different from the one on the current connectionIf an authorization code is rejected, start authorization again. Disconnect any conflicting connection first. If a refresh token is rejected, ask the user to reconnect Walk15 from your partner app.
unsupported_grant_type400grant_type is not authorization_code or refresh_tokenFix the request
unsupported_token_type400token_type_hint is not access_token or refresh_tokenFix or omit the hint
server_error500Walk15 could not complete the requestRetry later with backoff. If this happened during token refresh, do not resend the token; ask the user to reconnect Walk15 from your app.
temporarily_unavailable503Walk15 is temporarily unavailableRetry later with backoff. This also applies to token refresh: resend the same refresh token.

Activity and disconnect errors

CodeStatusMeaningWhat to do
invalid_request400Unknown or duplicate query parameter, request body present, malformed encoding, URL over 4096 characters, invalid limitFix the request
invalid_date_range400Missing or invalid dates, from after to, more than 31 dates, from before history_from or more than 30 days before today (UTC), from before the Walk15 registration day (summary with daily_steps:read), to after tomorrow (UTC)Follow Date range troubleshooting. Ranges are never trimmed automatically.
invalid_cursor400Cursor expired (15 minutes), changed, from another query/limit, or from an older connection versionRestart the traversal from the first page
invalid_access_token401Access token missing, malformed, expired, revoked; connection revoked or lapsed; user deleted; client disabledRefresh once if the access token expired. If refresh fails, follow When refresh fails.
insufficient_scope403The connection does not include this endpoint's scopeStop calling it, or reconnect the user with that scope
rate_limited429Your rate or concurrency budget is exhaustedWait Retry-After seconds; reduce concurrency
data_unavailable503Walk15 is temporarily unable to complete the requestRetry later with exponential backoff; keep your existing data

401 responses include WWW-Authenticate: Bearer realm="walk15-connect", error="invalid_token" and 403 responses error="insufficient_scope".

Retry only 429 (after Retry-After), 5xx and network errors (exponential backoff with jitter), and a 401 once after refreshing the access token. Never retry a refresh whose outcome is unknown. An error is never an empty result and never means data was deleted.

Date range troubleshooting

For 400 invalid_date_range, check that:

  • from and to are real calendar dates in YYYY-MM-DD form, and from is not after to;
  • the range includes at most 31 dates (to is at most 30 days after from);
  • from is on or after both history_from and 30 days before today in UTC;
  • to is no later than tomorrow in UTC.

Summary requests authorized for daily_steps:read also cannot start before the user's Walk15 registration day. That date is not returned in the token response and, in rare timezone-change cases, can be later than history_from. If the checks above pass but a summary request is still rejected, contact Walk15 with the requested dates and X-Request-ID. Do not retry the same range unchanged.

Rate limits

Walk15 sets a technical rate policy for each customer individually, based on your expected traffic. A policy has three parts:

PartMeaning
Requests per minuteSustained refill rate of your request budget
BurstHow many requests can be made back-to-back when the budget is full
Concurrent readsHow many activity reads Walk15 runs for you at the same time

The policy applies to all activity requests from your client combined, across all connected users, both activity endpoints and all your servers. Pace these reads centrally and keep concurrency within your allowance. Token, revoke and disconnect calls do not consume this activity request budget. Some unsuccessful reads do consume budget; see Request accounting for the exact rules.

Use these headers, when present, to track your request budget:

HeaderMeaning
RateLimit-LimitYour configured requests per minute
RateLimit-RemainingWhole requests currently left in your burst budget
RateLimit-ResetSeconds until the next request becomes available (minimum 1)
Retry-AfterOn 429 only: seconds to wait before retrying (minimum 1)

A 429 caused by the concurrency limit has Retry-After: 1.

Handling 429

  • Apply Retry-After to your whole worker pool, not just the one request, and keep parallel activity requests within your concurrency allowance.
  • Pace requests with a queue rather than fire-and-retry loops, and spread scheduled polling over time.
  • Many users sync at the same moment, so activity.updated arrives in bursts. Acknowledge events immediately and let workers drain the queue at your allowed rate.

The withRateLimitRetry helper in the TypeScript client shows a minimal per-request version.

Request accounting

Advanced reference for explaining budget use when requests fail:

  • Requests with a missing or invalid access token (401), a missing scope (403), or a malformed request (400 invalid_request for an unknown or repeated parameter, a body, malformed encoding or an over-long URL) are not counted.
  • Every activity request that passes those checks is counted, including invalid_date_range, invalid_cursor, an invalid limit and a 429 from the concurrency limit.
  • Token, revoke and disconnect calls are not counted.

Other limits

LimitValue
Dates per activity request31 (inclusive)
Cycling activities per page1–500 (default 100)
Authorization URL16 KB
Activity request URL4096 characters
OAuth request body8 KB, fields up to 2048 characters
application_user_id1–128 letters, digits, dots, underscores or hyphens
scope parameter512 characters
state parameter22–2048 characters
Authorization request10 minutes
Authorization code5 minutes at most
Access tokenfive minutes
Refresh inactivity90 days, the same for every customer
Cursor traversal15 minutes
Webhook response2xx within 5 seconds, body up to 8 KB