Docs navigation

Errors

Error envelope and status codes

All documented API errors use the same `error` envelope with a stable `code`, human-readable `message`, actionable `hint`, a `docs_url` linking to the relevant section below, and an optional `details` object.

Envelope

Shared error shape

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "hint": "Actionable next step to resolve this error",
    "docs_url": "https://exerciseapi.dev/docs/errors#ERROR_CODE",
    "details": {}
  }
}

INVALID_API_KEY401

Missing, malformed, or unknown API key.

Hint: Check the X-API-Key header. Keys start with exlib_ and are 38 characters.

Example

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing API key. Get one at https://exerciseapi.dev/signup",
    "hint": "Add the header: X-API-Key: exlib_your_key_here",
    "docs_url": "https://exerciseapi.dev/docs/errors#INVALID_API_KEY"
  }
}

RATE_LIMIT_EXCEEDED429

Per-minute or daily rate limit exceeded.

Hint: Honor the Retry-After header and back off. Upgrade for higher limits.

Details fields: upgrade_url, current_tier, limit, window, resets_at

Example

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Per-minute rate limit exceeded (60/min). Slow down.",
    "hint": "Wait 32s or upgrade your plan for a higher per-minute limit.",
    "docs_url": "https://exerciseapi.dev/docs/errors#RATE_LIMIT_EXCEEDED",
    "details": {
      "upgrade_url": "https://exerciseapi.dev/dashboard/billing",
      "current_tier": "free",
      "limit": 30,
      "window": "minute",
      "resets_at": "2026-04-02T18:15:00.000Z"
    }
  }
}

OVERAGE_CAP_EXCEEDED429

Paid tier exceeded the 10x daily safety cap. Requests blocked until midnight UTC.

Hint: Safety cap prevents runaway bills. Upgrade or contact support for a higher cap.

Details fields: upgrade_url, current_tier, daily_limit, safety_cap, total_requests_today, overage_requests_today, overage_cost_today, resets_at

Example

{
  "error": {
    "code": "OVERAGE_CAP_EXCEEDED",
    "message": "Daily overage safety limit reached (10x your plan). Contact support for higher limits.",
    "hint": "Safety cap prevents runaway bills. Resets at 2026-04-11T00:00:00.000Z. Upgrade your plan or contact support for a higher cap.",
    "docs_url": "https://exerciseapi.dev/docs/errors#OVERAGE_CAP_EXCEEDED",
    "details": {
      "upgrade_url": "https://exerciseapi.dev/dashboard/billing",
      "current_tier": "starter",
      "daily_limit": 1000,
      "safety_cap": 10000,
      "total_requests_today": 10000,
      "overage_requests_today": 9000,
      "overage_cost_today": "$18.00",
      "resets_at": "2026-04-11T00:00:00.000Z"
    }
  }
}

PAGINATION_DEPTH_EXCEEDED403

Free-tier request goes beyond the first 500 results.

Hint: Reduce offset + limit to 500 or below, or upgrade to a paid plan.

Details fields: upgrade_url, current_tier

Example

{
  "error": {
    "code": "PAGINATION_DEPTH_EXCEEDED",
    "message": "Free tier limited to first 500 results. Upgrade for full access.",
    "hint": "Reduce offset + limit to 500 or below, or upgrade to a paid plan for unlimited pagination.",
    "docs_url": "https://exerciseapi.dev/docs/errors#PAGINATION_DEPTH_EXCEEDED",
    "details": {
      "upgrade_url": "https://exerciseapi.dev/dashboard/billing",
      "current_tier": "free"
    }
  }
}

INVALID_PARAMETER400

Query parameter or path parameter validation failed.

Hint: Check the parameter name and value. Enum fields include allowed values in the hint.

Details fields: field, received, allowed

Example

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid query parameter: 'category' Invalid enum value",
    "hint": "Allowed values for 'category': strength, yoga, mobility, physical_therapy, stretching, pilates, calisthenics, plyometrics, conditioning, olympic_weightlifting, powerlifting, strongman",
    "docs_url": "https://exerciseapi.dev/docs/errors#INVALID_PARAMETER",
    "details": {
      "field": "category",
      "received": "chest",
      "allowed": [
        "strength",
        "yoga",
        "mobility",
        "physical_therapy",
        "stretching",
        "pilates",
        "calisthenics",
        "plyometrics",
        "conditioning",
        "olympic_weightlifting",
        "powerlifting",
        "strongman"
      ]
    }
  }
}

NOT_FOUND404

Requested resource does not exist.

Hint: Use GET /v1/exercises?q=<name> to search by name and get the correct ID.

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Exercise not found: Barbell_Bench_Press_-_Medium_Grip",
    "hint": "Check the exercise ID. Use GET /v1/exercises?q=<name> to search by name and get the correct ID.",
    "docs_url": "https://exerciseapi.dev/docs/errors#NOT_FOUND"
  }
}

INTERNAL_ERROR500

Unexpected server error.

Hint: Retry with exponential backoff. Check /v1/health if the issue persists.

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "hint": "This is a server-side issue. If it persists, check https://exerciseapi.dev/v1/health for service status.",
    "docs_url": "https://exerciseapi.dev/docs/errors#INTERNAL_ERROR"
  }
}