Docs navigation

Errors

Error envelope and status codes

All documented API errors use the same `error` envelope with a stable `code`, human-readable `message`, and optional `details` object.

Envelope

Shared error shape

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  }
}

INVALID_API_KEY401

Missing, malformed, or unknown API key.

Example

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing API key. Get one at https://exerciseapi.dev/signup"
  }
}

RATE_LIMIT_EXCEEDED429

Per-minute or daily rate limit exceeded.

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

Example

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Per-minute rate limit exceeded (5/min). Slow down.",
    "details": {
      "upgrade_url": "https://exerciseapi.dev/dashboard/billing",
      "current_tier": "free",
      "limit": 5,
      "window": "minute",
      "resets_at": "2026-04-02T18:15:00.000Z"
    }
  }
}

PAGINATION_DEPTH_EXCEEDED403

Free-tier request goes beyond the first 500 results.

Details fields: upgrade_url, current_tier

Example

{
  "error": {
    "code": "PAGINATION_DEPTH_EXCEEDED",
    "message": "Free tier limited to first 500 results. Upgrade for full access.",
    "details": {
      "upgrade_url": "https://exerciseapi.dev/dashboard/billing",
      "current_tier": "free"
    }
  }
}

INVALID_PARAMETER400

Query parameter or path parameter validation failed.

Details fields: field, received

Example

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid query parameter: 'limit' Number must be less than or equal to 100",
    "details": {
      "field": "limit",
      "received": "500"
    }
  }
}

NOT_FOUND404

Requested resource does not exist.

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Exercise not found: barbell-bench-press"
  }
}

INTERNAL_ERROR500

Unexpected server error.

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}