Error Handling

Saturday uses one error format across all endpoints, modeled on Stripe’s error structure.

Error format

{
  "error": {
    "type": "invalid_request",
    "code": "missing_field",
    "message": "activity_type is required",
    "param": "activity_type",
    "documentation_url": "https://docs.saturday.fit/errors#missing_field",
    "request_id": "req_abc123def456"
  }
}

Field	Always present	Description
`type`	Yes	Category of error
`code`	Yes	Specific error code, machine-readable
`message`	Yes	Human-readable explanation
`param`	No	The request parameter that caused the error
`documentation_url`	Yes	Docs link for this code
`request_id`	Yes	Identifier for this request. Include it in support tickets

Error types

Branch on type for handling class, and on code for the specific case. A type can span more than one status.

Type	Statuses	Description
`invalid_request`	400, 409, 410	Malformed body, missing or out-of-range field, or a request that conflicts with current state
`authentication_error`	401, 403	Missing or invalid key (401), revoked key or suspended account (403)
`authorization_error`	403	Valid credentials, insufficient permission, scope, tier, or feature access
`not_found_error`	404	The URL does not match an endpoint available to your key
`resource_not_found`	404	The endpoint exists, but the referenced resource doesn’t, or belongs to another partner
`rate_limit_error`	429	Rate limit, daily call ceiling, or request-pattern friction
`api_error`	500, 502, 503	Saturday-side failure (500), upstream service (502), transient dependency (503)

A 404 carries one of two types. not_found_error means the URL itself found no endpoint (including endpoints not available to your key), always with code: "resource_not_found". resource_not_found as a type comes from an endpoint that could not find the thing you referenced, and its code narrows it: athlete_not_found, activity_not_found, key_not_found, webhook_not_found, conversation_not_found. Handle both types as the same case unless you need the distinction. A 429 carries type: "rate_limit_error" with code: "rate_limit_exceeded" or code: "rate_limited". Switching on type means using the values in the table above.

Safety ceilings do not surface as an error status. A prescription that runs into a guardrail returns 200 with the clamped values plus safety.warnings and safety.requires_human_review set. See Safety.

Retry logic

Type	Retry?	Strategy
`authentication_error`	No	Fix credentials
`authorization_error`	No	Fix permissions, scopes, or tier
`invalid_request`	No	Fix the request
`not_found_error`	No	Check the URL and your key’s feature access
`resource_not_found`	No	Fix the resource ID
`rate_limit_error`	Yes	Honor `Retry-After` when present, otherwise back off. See Rate Limiting
`api_error`	Yes	Exponential backoff. A 503 from key verification is transient: retry, don’t rotate the key

Exponential backoff

Retry-After is absent on some 429s, notably the daily call ceiling, so read it with a fallback rather than indexing it directly.

import time
import random

def request_with_retry(make_request, max_retries=3):
    for attempt in range(max_retries + 1):
        response = make_request()

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue

        if response.status_code >= 500:
            if attempt < max_retries:
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
                continue

        return response

    return response

async function requestWithRetry(
  makeRequest: () => Promise<Response>,
  maxRetries = 3
): Promise<Response> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await makeRequest();

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") ?? "60");
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    if (response.status >= 500 && attempt < maxRetries) {
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      await new Promise((r) => setTimeout(r, delay));
      continue;
    }

    return response;
  }

  throw new Error("Max retries exceeded");
}

Request IDs

Every response carries an X-Request-Id header, and every error body repeats it as request_id. Quote it when reporting an issue and we can trace that exact request.

Error catalog

GET /v1/errors (no auth) lists the error codes for the features currently exposed to you.

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Error Handling

Error Handling

Error format

Error types

Retry logic

Exponential backoff

Request IDs

Error catalog

​Error Handling

​Error format

​Error types

​Retry logic

​Exponential backoff

​Request IDs

​Error catalog

Error Handling

Error format

Error types

Retry logic

Exponential backoff

Request IDs

Error catalog